[all][doc] the openstack-tox-docs job is broken with Sphinx >= 5.0.0
Hi, It seems the openstack-tox-docs job is broken in some projects because of the following change made in Sphinx >= 5.0.0 . https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8... We currently have Sphinx 4.5.0 in upper-constraints.txt but some projects (eg. Heat, Nova, Neutron) are using only their own docs-constraints.txt and pull the latest version which is 5.0.1 . IMO we need to fix the problem by the following two steps, but I'd appreciate if anybody can share a better idea. 1. Update tox.ini to honor upper-constraints.txt. This is needed in master and stable/branches as well. 2. Update docs/source/conf.py to hard-code the language parameter to 'en'. This is required in master so that we can bump the upper version later. Thank you, Takashi Kajinami
Sorry it seems I was looking at something wrong and it seems the projects I mentioned as examples(Heat, Nova and Neutron) are already using upper constraints for doc build. However I'd recommend reach project reviews their current tox.ini. Updating conf.py would be still required so it's better to work on it earlier before the upper constraint is updated. On Mon, Jun 6, 2022 at 1:15 PM Takashi Kajinami <tkajinam@redhat.com> wrote:
Hi,
It seems the openstack-tox-docs job is broken in some projects because of the following change made in Sphinx >= 5.0.0 .
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
We currently have Sphinx 4.5.0 in upper-constraints.txt but some projects (eg. Heat, Nova, Neutron) are using only their own docs-constraints.txt and pull the latest version which is 5.0.1 .
IMO we need to fix the problem by the following two steps, but I'd appreciate if anybody can share a better idea.
1. Update tox.ini to honor upper-constraints.txt. This is needed in master and stable/branches as well.
2. Update docs/source/conf.py to hard-code the language parameter to 'en'. This is required in master so that we can bump the upper version later.
Thank you, Takashi Kajinami
On 6/6/22 12:27 AM, Takashi Kajinami wrote: [snip]
Updating conf.py would be still required so it's better to work on it earlier before the upper constraint is updated.
I was just looking into this, and as long as your conf.py does not explicitly set language = None the default language is set to 'en' internally by Sphinx in 5.0.0+ [0]. So as long as you have the language setting either missing or commented out in your conf.py, you should not see this warning (which, when treated as an error, breaks the doc build). [0] https://github.com/sphinx-doc/sphinx/commit/e4e58a4f2791e528cdaa861b96636a1e...
On Mon, Jun 6, 2022 at 1:15 PM Takashi Kajinami <tkajinam@redhat.com <mailto:tkajinam@redhat.com>> wrote:
Hi,
It seems the openstack-tox-docs job is broken in some projects because of the following change made in Sphinx >= 5.0.0 . https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8... <https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8d69e4180>
We currently have Sphinx 4.5.0 in upper-constraints.txt but some projects (eg. Heat, Nova, Neutron) are using only their own docs-constraints.txt and pull the latest version which is 5.0.1 .
IMO we need to fix the problem by the following two steps, but I'd appreciate if anybody can share a better idea.
1. Update tox.ini to honor upper-constraints.txt. This is needed in master and stable/branches as well.
2. Update docs/source/conf.py to hard-code the language parameter to 'en'. This is required in master so that we can bump the upper version later.
Thank you, Takashi Kajinami
Thanks Brian, Actually I hit this problem initially with heat-cfntools which is not using upper-constraints in doc build but has language=None explicitly set, so what you mentioned makes quite clear sense. Quick grep shows a few instances of the hard-coded language=None . These should be commented out before we get the constraint bumped. openstack/python-swiftclient/releasenotes/source/conf.py:language = None openstack/blazar/api-ref/source/conf.py:language = None openstack/heat-agents/doc/source/conf.py:language = None openstack/heat-agents/releasenotes/source/conf.py:language = None openstack/swift/releasenotes/source/conf.py:language = None openstack/storlets/releasenotes/source/conf.py:language = None openstack/placement/releasenotes/source/conf.py:language = None openstack/osc-lib/releasenotes/source/conf.py:language = None openstack/python-heatclient/releasenotes/source/conf.py:language = None openstack/trove-dashboard/releasenotes/source/conf.py:language = None openstack/virtualbmc/releasenotes/source/conf.py:language = None openstack/heat-templates/doc/source/conf.py:language = None Disclaimer: The above list might be missing some projects. On Mon, Jun 6, 2022 at 10:19 PM Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
On 6/6/22 12:27 AM, Takashi Kajinami wrote: [snip]
Updating conf.py would be still required so it's better to work on it earlier before the upper constraint is updated.
I was just looking into this, and as long as your conf.py does not explicitly set language = None the default language is set to 'en' internally by Sphinx in 5.0.0+ [0]. So as long as you have the language setting either missing or commented out in your conf.py, you should not see this warning (which, when treated as an error, breaks the doc build).
[0]
https://github.com/sphinx-doc/sphinx/commit/e4e58a4f2791e528cdaa861b96636a1e...
On Mon, Jun 6, 2022 at 1:15 PM Takashi Kajinami <tkajinam@redhat.com <mailto:tkajinam@redhat.com>> wrote:
Hi,
It seems the openstack-tox-docs job is broken in some projects because of the following change made in Sphinx >= 5.0.0 .
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
<
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
We currently have Sphinx 4.5.0 in upper-constraints.txt but some projects (eg. Heat, Nova, Neutron) are using only their own docs-constraints.txt and pull the latest version which is 5.0.1 .
IMO we need to fix the problem by the following two steps, but I'd appreciate if anybody can share a better idea.
1. Update tox.ini to honor upper-constraints.txt. This is needed in master and stable/branches as well.
2. Update docs/source/conf.py to hard-code the language parameter to 'en'. This is required in master so that we can bump the upper version later.
Thank you, Takashi Kajinami
Thank you Takashi for raising this. I also found one in the release notes configuration for python-blazarclient. I will fix the blazar repositories. On Mon, 6 Jun 2022 at 16:22, Takashi Kajinami <tkajinam@redhat.com> wrote:
Thanks Brian,
Actually I hit this problem initially with heat-cfntools which is not using upper-constraints in doc build but has language=None explicitly set, so what you mentioned makes quite clear sense.
Quick grep shows a few instances of the hard-coded language=None . These should be commented out before we get the constraint bumped.
openstack/python-swiftclient/releasenotes/source/conf.py:language = None openstack/blazar/api-ref/source/conf.py:language = None openstack/heat-agents/doc/source/conf.py:language = None openstack/heat-agents/releasenotes/source/conf.py:language = None openstack/swift/releasenotes/source/conf.py:language = None openstack/storlets/releasenotes/source/conf.py:language = None openstack/placement/releasenotes/source/conf.py:language = None openstack/osc-lib/releasenotes/source/conf.py:language = None openstack/python-heatclient/releasenotes/source/conf.py:language = None openstack/trove-dashboard/releasenotes/source/conf.py:language = None openstack/virtualbmc/releasenotes/source/conf.py:language = None openstack/heat-templates/doc/source/conf.py:language = None
Disclaimer: The above list might be missing some projects.
On Mon, Jun 6, 2022 at 10:19 PM Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
On 6/6/22 12:27 AM, Takashi Kajinami wrote: [snip]
Updating conf.py would be still required so it's better to work on it earlier before the upper constraint is updated.
I was just looking into this, and as long as your conf.py does not explicitly set language = None the default language is set to 'en' internally by Sphinx in 5.0.0+ [0]. So as long as you have the language setting either missing or commented out in your conf.py, you should not see this warning (which, when treated as an error, breaks the doc build).
[0]
https://github.com/sphinx-doc/sphinx/commit/e4e58a4f2791e528cdaa861b96636a1e...
On Mon, Jun 6, 2022 at 1:15 PM Takashi Kajinami <tkajinam@redhat.com <mailto:tkajinam@redhat.com>> wrote:
Hi,
It seems the openstack-tox-docs job is broken in some projects because of the following change made in Sphinx >= 5.0.0 .
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
<
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
We currently have Sphinx 4.5.0 in upper-constraints.txt but some projects (eg. Heat, Nova, Neutron) are using only their own docs-constraints.txt and pull the latest version which is 5.0.1 .
IMO we need to fix the problem by the following two steps, but I'd appreciate if anybody can share a better idea.
1. Update tox.ini to honor upper-constraints.txt. This is needed in master and stable/branches as well.
2. Update docs/source/conf.py to hard-code the language parameter to 'en'. This is required in master so that we can bump the upper version later.
Thank you, Takashi Kajinami
Cursory search appears to indicate that these are part of some boilerplate configuration code. So I believe we should be fine if we remove it. Still, I wonder why was the language set to `None` in the first place. On Mon, Jun 6, 2022 at 4:21 PM Takashi Kajinami <tkajinam@redhat.com> wrote:
Thanks Brian,
Actually I hit this problem initially with heat-cfntools which is not using upper-constraints in doc build but has language=None explicitly set, so what you mentioned makes quite clear sense.
Quick grep shows a few instances of the hard-coded language=None . These should be commented out before we get the constraint bumped.
openstack/python-swiftclient/releasenotes/source/conf.py:language = None openstack/blazar/api-ref/source/conf.py:language = None openstack/heat-agents/doc/source/conf.py:language = None openstack/heat-agents/releasenotes/source/conf.py:language = None openstack/swift/releasenotes/source/conf.py:language = None openstack/storlets/releasenotes/source/conf.py:language = None openstack/placement/releasenotes/source/conf.py:language = None openstack/osc-lib/releasenotes/source/conf.py:language = None openstack/python-heatclient/releasenotes/source/conf.py:language = None openstack/trove-dashboard/releasenotes/source/conf.py:language = None openstack/virtualbmc/releasenotes/source/conf.py:language = None openstack/heat-templates/doc/source/conf.py:language = None
Disclaimer: The above list might be missing some projects.
On Mon, Jun 6, 2022 at 10:19 PM Brian Rosmaita <rosmaita.fossdev@gmail.com> wrote:
On 6/6/22 12:27 AM, Takashi Kajinami wrote: [snip]
Updating conf.py would be still required so it's better to work on it earlier before the upper constraint is updated.
I was just looking into this, and as long as your conf.py does not explicitly set language = None the default language is set to 'en' internally by Sphinx in 5.0.0+ [0]. So as long as you have the language setting either missing or commented out in your conf.py, you should not see this warning (which, when treated as an error, breaks the doc build).
[0]
https://github.com/sphinx-doc/sphinx/commit/e4e58a4f2791e528cdaa861b96636a1e...
On Mon, Jun 6, 2022 at 1:15 PM Takashi Kajinami <tkajinam@redhat.com <mailto:tkajinam@redhat.com>> wrote:
Hi,
It seems the openstack-tox-docs job is broken in some projects because of the following change made in Sphinx >= 5.0.0 .
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
<
https://github.com/sphinx-doc/sphinx/commit/a3d09835522e6487cf93dcc871179db8...
We currently have Sphinx 4.5.0 in upper-constraints.txt but some projects (eg. Heat, Nova, Neutron) are using only their own docs-constraints.txt and pull the latest version which is 5.0.1 .
IMO we need to fix the problem by the following two steps, but I'd appreciate if anybody can share a better idea.
1. Update tox.ini to honor upper-constraints.txt. This is needed in master and stable/branches as well.
2. Update docs/source/conf.py to hard-code the language parameter to 'en'. This is required in master so that we can bump the upper version later.
Thank you, Takashi Kajinami
participants (4)
-
Brian Rosmaita
-
Jiri Podivin
-
Pierre Riteau
-
Takashi Kajinami