[all][doc] the openstack-tox-docs job is broken with Sphinx >= 5.0.0

Takashi Kajinami tkajinam at redhat.com
Mon Jun 6 14:15:54 UTC 2022


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 at 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/e4e58a4f2791e528cdaa861b96636a1e37a558ba
>
> >
> > On Mon, Jun 6, 2022 at 1:15 PM Takashi Kajinami <tkajinam at redhat.com
> > <mailto:tkajinam at 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/a3d09835522e6487cf93dcc871179db8d69e4180
> >     <
> 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
> >
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20220606/cb000d31/attachment-0001.htm>


More information about the openstack-discuss mailing list