I noticed an incompatibility with the Sphinx i18n process for `docs.krita.org`. At the moment, the Binary Factory build is running Sphinx 4.0.x, but it appears that Scripty is building the POT templates using a Sphinx version before 4. In the Sphinx changelog for release 4.0.0 (https://www.sphinx-doc.org/en/master/changes.html#id18), these changes are listed: - #7784: i18n: The msgid for alt text of image is changed - #7784: i18n: The alt text for image is translated by default (without gettext_additional_targets setting) The first change is breaking because it means the POT templates generated by Sphinx <4 now contains image alt text in a format that does not get used by Sphinx 4. This can be observed on the page https://docs.krita.org/ca/404.html (check the `alt` attribute from HTML source or dev tools) - https://invent.kde.org/documentation/docs-krita-org/-/blob/krita/4.3/locale/ca/LC_MESSAGES/404.po#L31 However, switching the POT generation to Sphinx 4 has its issues. It seems to be outputting message entries for everything in `rst_epilog` into every single POT files, instead of only in the files that uses them. I have opened an upstream issue for this: https://github.com/sphinx-doc/sphinx/issues/9428 What would be the best course of action? I don't think we should downgrade Sphinx on the builder (as there had been some HTML output changes), but upgrading it for Scripty also poses some issues.
Just an FYI update: I have an upstream patch that will allow us to use 4.x to generate POT files without the redundant messages: https://github.com/sphinx-doc/sphinx/pull/9454
Until the issue you reported on sphinx is fixed and new sphinx packages available on pypi.org, I'd say it's better not to upgrade. I would also argue that the builder should be moved back on sphinx 3 and use the version as scripty.
(In reply to Luigi Toscano from comment #2) > I would also argue that the builder should be moved back on sphinx 3 and use > the version as scripty. Actually it might not matter this time. When I made this report I hadn't looked at the Sphinx source, but now I suspect that Sphinx had never extracted the correct image links for translations (that is before the fix I suggested). So even if the binary-factory builder is rolled back to Sphinx 3.4 or 3.5 the alt-texts will still not be translated. Haven't actually verified it though. I guess it's fine to keep the current versions of Sphinx, since the translations for alt-texts have probably been broken since the beginning. For the long term however, perhaps we should try to keep the two of Scripty and binary-factory at the same Sphinx version. CC'ing Ben...
(In reply to Alvin Wong from comment #3) > For the long term however, perhaps we should try to keep the two of Scripty > and binary-factory at the same Sphinx version. I agree, that's why the requested version of sphinx should be documented (requirements.txt?) and capped, and uncapped to new major versions (x.y) after some testing.
Sphinx is installed as part of our Docker images - therefore any change will need to be made there. See system-images/static-websites/Dockerfile in sysadmin/ci-tooling. Please note that I think a couple of other projects use Sphinx as well, so you should likely check with them that this won't introduce any issues.
@Ben: We don't need to downgrade now, but would you have any suggestions on synchronizing the versions of Sphinx on the binary factory and Scripty in the future? We can add a requirements.txt to the docs repo, but we would still need to update the two manually whenever we bump the Sphinx version. Does setting up a project-specific Python venv from the requirements.txt for the build and Scripty make sense, or would the extra time and bandwidth taken make it a bad idea?
(In reply to Alvin Wong from comment #6) > @Ben: We don't need to downgrade now, but would you have any suggestions on > synchronizing the versions of Sphinx on the binary factory and Scripty in > the future? We can add a requirements.txt to the docs repo, but we would > still need to update the two manually whenever we bump the Sphinx version. I'd say just use the common way to define dependencies in python, as discussed. I'd also argue that we can evaluate a downgrade now. And we also may have the same issue again if the other users of sphinx need to depend on different versions of sphinx (we may need different images or some kind of coordination anyway).
Because we install Sphinx as part of the Docker image we'll need to specify the version in the Dockerfile as well. Due to the risk of external systems failing (as Craft and Krita see sometimes with their dependency builds, when remote providers of tarballs sometimes go down) i'd very much prefer to keep it baked into the image to ensure any failures outside of our systems don't prevent us from rebuilding websites.
(In reply to Ben Cooksley from comment #8) > Because we install Sphinx as part of the Docker image we'll need to specify > the version in the Dockerfile as well. How about when building the Docker image we download the reauirements.txt from the Krita docs repo (we shall add one) and set up a project-specific venv in there? Then we don't have to worry about affecting other projects that use Sphinx, and we don't need to keep track of versioning in multiple places (but we still need to ask for the image to be rebuilt when we change requirements).
We may be able to simplify that further. Looking at it, the only other sites using it now are sysadmin-docs.kde.org and openraster.org (which Halla knows more about) so I think it should be fairly safe to skip the docs.krita.org specific venv.
Um, do we still need this report open, or can we close it?
This issue still exists for the current build of the manual. I have not checked recent versions of Sphinx, but given there had been no updates to the issues and pull requests upstream I'd guess it's probably still broken.