OpenStack should be buildable with sphinx 2.4: FTBFS in many packages
Hi, Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list: - ironic - os-api-ref - aodh - cloudkitty - kombu - panko - ceilometerclient - ceilometermiddleware - doc8 - dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput - tempest-horizon It'd be nice if those affected could be fixed for Ussuri. IMO, it's just the doc, so fixing it wouldn't hurt code quality. In other words: help would be more than welcome writing patch or reviewing them, and testing Sphinx 2.4 compatibility. Cheers, Thomas Goirand (zigo)
Hi Thomas, Thanks for raising this, I will take a look at the ironic documentation to make it compatible with Sphinx 2.4. Em sáb., 28 de mar. de 2020 às 06:32, Thomas Goirand <zigo@debian.org> escreveu:
Hi,
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref - aodh - cloudkitty - kombu - panko - ceilometerclient - ceilometermiddleware - doc8 - dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput - tempest-horizon
It'd be nice if those affected could be fixed for Ussuri. IMO, it's just the doc, so fixing it wouldn't hurt code quality. In other words: help would be more than welcome writing patch or reviewing them, and testing Sphinx 2.4 compatibility.
Cheers,
Thomas Goirand (zigo)
-- *Att[]'sIury Gregory Melo Ferreira * *MSc in Computer Science at UFCG* *Part of the puppet-manager-core team in OpenStack* *Software Engineer at Red Hat Czech* *Social*: https://www.linkedin.com/in/iurygregory *E-mail: iurygregory@gmail.com <iurygregory@gmail.com>*
Hi, Find my comments on several repositories. On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org> wrote:
Hi,
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
- aodh - cloudkitty - kombu
This is not part of OpenStack and is not found in opendev.org.
- panko - ceilometerclient - ceilometermiddleware - doc8
doc8 was retired Jul 2019.
- dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput
This is not part of OpenStack and is not found in opendev.org.
- tempest-horizon
sphinx document is not actually used and the content was not changed under the initial cookiecutter commit. I proposed a patch to drop sphinx related stuffs. Hope it works for you.
It'd be nice if those affected could be fixed for Ussuri. IMO, it's just the doc, so fixing it wouldn't hurt code quality. In other words: help would be more than welcome writing patch or reviewing them, and testing Sphinx 2.4 compatibility.
Cheers,
Thomas Goirand (zigo)
Hi there! Thanks for your reply. On 3/28/20 10:05 PM, Akihiro Motoki wrote:
On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org> wrote:
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
For Ironic, the bug report is here: https://bugs.debian.org/955069 For os-api-ref, here: https://bugs.debian.org/955098 the bug in os-api-ref is *not* in its documentation, but in os-api-ref itself, unfortunately (failure to run unit tests...).
- aodh - cloudkitty - kombu
This is not part of OpenStack and is not found in opendev.org.
Kombu, probably, however it's used in many OpenStack projects, like taskflow, oslo.messaging, ceilometer, heat, mistral, murano... The other 2 really are in opendev: https://opendev.org/openstack/cloudkitty https://opendev.org/openstack/aodh
- dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput
This is not part of OpenStack and is not found in opendev.org.
Does your sentence intend to apply to all what you've quoted? :) Hopefully not ... and assuming not: sphinxcontrib-programoutput is used in many docs in OpenStack, so it is also relevant to have it in the list.
- tempest-horizon
sphinx document is not actually used and the content was not changed under the initial cookiecutter commit. I proposed a patch to drop sphinx related stuffs. Hope it works for you.
Thanks. I'll drop the doc package then. Cheers, Thomas Goirand (zigo)
On Sun, Mar 29, 2020 at 7:36 AM Thomas Goirand <zigo@debian.org> wrote:
Hi there!
Thanks for your reply.
On 3/28/20 10:05 PM, Akihiro Motoki wrote:
On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org> wrote:
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
For Ironic, the bug report is here: https://bugs.debian.org/955069
For os-api-ref, here: https://bugs.debian.org/955098
the bug in os-api-ref is *not* in its documentation, but in os-api-ref itself, unfortunately (failure to run unit tests...).
All os-api-ref unittests succeed in the OpenStack CI. For example, https://zuul.opendev.org/t/openstack/build/af69856854424ef59d7b096f4dbffc1b It uses sphinx 2.4.4 and sphinx-testing 1.0.1. At a quick look of sphinx-testing, os-api-ref tests only works with os-api-ref>=1.0.1, while test-requirements.txt says os-api-ref>=0.7.2. read_text() method is from sphinx_testing.path.path class, but up to sphinx-testing 1.0.0 str is returned as app.outdir. The simplest solution would be to update test-requirements.txt to os-api-ref>=1.0.1 to clarify the requirements. Perhaps Debian testing uses sphinx-testing <1.0.1.
- aodh - cloudkitty - kombu
This is not part of OpenStack and is not found in opendev.org.
Kombu, probably, however it's used in many OpenStack projects, like taskflow, oslo.messaging, ceilometer, heat, mistral, murano...
My intention is to refer only kombu, so I used "This". You mentioned "OpenStack packages" so I just would like to clarify it. Of course, it would be nice to fix them.
The other 2 really are in opendev:
https://opendev.org/openstack/cloudkitty https://opendev.org/openstack/aodh
- dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput
This is not part of OpenStack and is not found in opendev.org.
Does your sentence intend to apply to all what you've quoted? :) Hopefully not ... and assuming not:
sphinxcontrib-programoutput is used in many docs in OpenStack, so it is also relevant to have it in the list.
Same as the above.
- tempest-horizon
sphinx document is not actually used and the content was not changed under the initial cookiecutter commit. I proposed a patch to drop sphinx related stuffs. Hope it works for you.
Thanks. I'll drop the doc package then.
- doc8 doc8 was retired Jul 2019.
One correction on doc8. The repository was retired, but more precisely, as mentioned at https://opendev.org/x/doc8, it was moved to https://github.com/PyCQA/doc8 Thanks, Akihiro
Cheers,
Thomas Goirand (zigo)
On 3/29/20 5:47 AM, Akihiro Motoki wrote:
On Sun, Mar 29, 2020 at 7:36 AM Thomas Goirand <zigo@debian.org> wrote:
Hi there!
Thanks for your reply.
On 3/28/20 10:05 PM, Akihiro Motoki wrote:
On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org> wrote:
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
For Ironic, the bug report is here: https://bugs.debian.org/955069
For os-api-ref, here: https://bugs.debian.org/955098
the bug in os-api-ref is *not* in its documentation, but in os-api-ref itself, unfortunately (failure to run unit tests...).
All os-api-ref unittests succeed in the OpenStack CI. For example, https://zuul.opendev.org/t/openstack/build/af69856854424ef59d7b096f4dbffc1b It uses sphinx 2.4.4 and sphinx-testing 1.0.1.
At a quick look of sphinx-testing, os-api-ref tests only works with os-api-ref>=1.0.1, while test-requirements.txt says os-api-ref>=0.7.2. read_text() method is from sphinx_testing.path.path class, but up to sphinx-testing 1.0.0 str is returned as app.outdir. The simplest solution would be to update test-requirements.txt to os-api-ref>=1.0.1 to clarify the requirements. Perhaps Debian testing uses sphinx-testing <1.0.1.
Oh, this is super useful, thanks! Indeed, sphinx-testing is in version 0.8.1 in Debian Sid. So I guess my next course of action is to reassign the bug to sphinx-testing. One thing less to take care of! :) Cheers, Thomas Goirand (zigo)
On Sat, Mar 28, 2020 at 10:08 PM Akihiro Motoki <amotoki@gmail.com> wrote:
Hi,
Find my comments on several repositories.
On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org> wrote:
Hi,
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
- aodh - cloudkitty - kombu
This is not part of OpenStack and is not found in opendev.org.
- panko - ceilometerclient - ceilometermiddleware - doc8
doc8 was retired Jul 2019.
For those like me who just nearly had a heart attack: it wasn't fully retired, it was moved (?) to https://github.com/PyCQA/doc8
- dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput
This is not part of OpenStack and is not found in opendev.org.
- tempest-horizon
sphinx document is not actually used and the content was not changed under the initial cookiecutter commit. I proposed a patch to drop sphinx related stuffs. Hope it works for you.
It'd be nice if those affected could be fixed for Ussuri. IMO, it's just the doc, so fixing it wouldn't hurt code quality. In other words: help would be more than welcome writing patch or reviewing them, and testing Sphinx 2.4 compatibility.
Cheers,
Thomas Goirand (zigo)
On Sun, Mar 29, 2020 at 10:37 PM Dmitry Tantsur <dtantsur@redhat.com> wrote:
On Sat, Mar 28, 2020 at 10:08 PM Akihiro Motoki <amotoki@gmail.com> wrote:
Hi,
Find my comments on several repositories.
On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org> wrote:
Hi,
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
- aodh - cloudkitty - kombu
This is not part of OpenStack and is not found in opendev.org.
- panko - ceilometerclient - ceilometermiddleware - doc8
doc8 was retired Jul 2019.
For those like me who just nearly had a heart attack: it wasn't fully retired, it was moved (?) to https://github.com/PyCQA/doc8
Yeah, my first email was not enough and I sent a follow-up. --- One correction on doc8. The repository was retired, but more precisely, as mentioned at https://opendev.org/x/doc8, it was moved to https://github.com/PyCQA/doc8 ---
- dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput
This is not part of OpenStack and is not found in opendev.org.
- tempest-horizon
sphinx document is not actually used and the content was not changed under the initial cookiecutter commit. I proposed a patch to drop sphinx related stuffs. Hope it works for you.
It'd be nice if those affected could be fixed for Ussuri. IMO, it's just the doc, so fixing it wouldn't hurt code quality. In other words: help would be more than welcome writing patch or reviewing them, and testing Sphinx 2.4 compatibility.
Cheers,
Thomas Goirand (zigo)
What is the goal for Sphinx 2.4? From: Dmitry Tantsur <dtantsur@redhat.com> Sent: Sunday, March 29, 2020 8:34 AM To: openstack-discuss Subject: Re: OpenStack should be buildable with sphinx 2.4: FTBFS in many packages [EXTERNAL EMAIL] On Sat, Mar 28, 2020 at 10:08 PM Akihiro Motoki <amotoki@gmail.com<mailto:amotoki@gmail.com>> wrote: Hi, Find my comments on several repositories. On Sat, Mar 28, 2020 at 6:34 PM Thomas Goirand <zigo@debian.org<mailto:zigo@debian.org>> wrote:
Hi,
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
- ironic - os-api-ref
I can build the document with sphinx 2.4.4.
- aodh - cloudkitty - kombu
This is not part of OpenStack and is not found in opendev.org<http://opendev.org>.
- panko - ceilometerclient - ceilometermiddleware - doc8
doc8 was retired Jul 2019. For those like me who just nearly had a heart attack: it wasn't fully retired, it was moved (?) to https://github.com/PyCQA/doc8
- dracclient - glareclient - murano-pkg-check - os-xenapi - scciclient - sahara - sphinxcontrib-programoutput
This is not part of OpenStack and is not found in opendev.org<http://opendev.org>.
- tempest-horizon
sphinx document is not actually used and the content was not changed under the initial cookiecutter commit. I proposed a patch to drop sphinx related stuffs. Hope it works for you.
It'd be nice if those affected could be fixed for Ussuri. IMO, it's just the doc, so fixing it wouldn't hurt code quality. In other words: help would be more than welcome writing patch or reviewing them, and testing Sphinx 2.4 compatibility.
Cheers,
Thomas Goirand (zigo)
On 2020-03-29 22:15:23 +0000 (+0000), Arkady.Kanevsky@dell.com wrote:
What is the goal for Sphinx 2.4? [...]
Lots of software projects rely on Sphinx to build their documentation, and GNU/Linux distributions are typically not going to want to have to find a way to carry more than one version of it. Making sure OpenStack projects' documentation can be packaged with the latest releases of Sphinx helps ease the maintenance burden on distributions and integrators. -- Jeremy Stanley
Thanks Jeremy. I would assume we want all openstack doc per release follow this, including all drivers? Thanks, Arkady -----Original Message----- From: Jeremy Stanley <fungi@yuggoth.org> Sent: Sunday, March 29, 2020 5:22 PM To: openstack-discuss@lists.openstack.org Subject: Re: OpenStack should be buildable with sphinx 2.4: FTBFS in many packages On 2020-03-29 22:15:23 +0000 (+0000), Arkady.Kanevsky@dell.com wrote:
What is the goal for Sphinx 2.4? [...]
Lots of software projects rely on Sphinx to build their documentation, and GNU/Linux distributions are typically not going to want to have to find a way to carry more than one version of it. Making sure OpenStack projects' documentation can be packaged with the latest releases of Sphinx helps ease the maintenance burden on distributions and integrators. -- Jeremy Stanley
On 2020-03-29 23:41:03 +0000 (+0000), Arkady.Kanevsky@dell.com wrote:
I would assume we want all openstack doc per release follow this, including all drivers?
Correct, our upper-constraints.txt[0] file actually specifies which version of Sphinx projects should be using to test their documentation builds, as of this moment Sphinx===2.4.4 for master branch docs jobs if run under Python 3.6 or 3.7 (our "tested runtimes" for the Ussuri cycle[1]). I'm somewhat curious why these problems weren't caught sooner, given that. Are those projects running with a different Python interpreter version? Or without global constraints applied? Or perhaps they're not testing documentation builds at all when merging changes? We've basically been telling projects to test[2] with Sphinx 2.4 since 2.4.0 was first released[3] in February. [0] https://opendev.org/openstack/requirements/src/branch/master/upper-constrain... [1] https://governance.openstack.org/tc/reference/runtimes/ussuri.html [2] https://review.opendev.org/705380 [3] https://pypi.org/project/Sphinx/2.4.0/#history -- Jeremy Stanley
On 3/30/20 7:14 PM, Jeremy Stanley wrote:
Are those projects running with a different Python interpreter version? Or without global constraints applied? Or perhaps they're not testing documentation builds at all when merging changes? We've basically been telling projects to test[2] with Sphinx 2.4 since 2.4.0 was first released[3] in February.
The packages in Debian are still the Train release, which is why they aren't up-to-date yet. I am forecasting that an upgrade to Ussuri will fix most of them. FYI, here's the list of bugs currently opened against the OpenStack packages in Debian: python-k8sclient https://bugs.debian.org/955062 python-doc8 https://bugs.debian.org/955070 python-dracclient https://bugs.debian.org/955073 aodh https://bugs.debian.org/955078 python-ceilometermiddleware https://bugs.debian.org/955080 panko https://bugs.debian.org/955084 python-glareclient https://bugs.debian.org/955085 sahara https://bugs.debian.org/955088 python-ceilometerclient https://bugs.debian.org/955091 python-scciclient https://bugs.debian.org/955102 cloudkitty https://bugs.debian.org/955108 python-os-xenapi https://bugs.debian.org/955113 python-murano-pkg-check https://bugs.debian.org/955116 sahara-plugin-vanilla https://bugs.debian.org/955433 I probably will wait until the OpenStack Ussuri release happen before taking care of most of the issues above, as they may just resolve themselves by just uploading the latest version (hopefully). I may as well remove from Debian packages like: - python-glareclient - python-ceilometerclient Is os-xenapi still of any use with recent OpenStack? Cheers, Thomas Goirand (zigo)
On Saturday, 28 March 2020 10:29:44 CEST Thomas Goirand wrote:
Hi,
Sphinx 2.4 has been uploaded to Experimental. I just received bug reports against the OpenStack packages because some of them cannot be built with Sphinx 2.4. Here's the list:
[...] - sahara
Sahara should have been fixed by: https://review.opendev.org/#/c/710658/ -- Luigi
participants (7)
-
Akihiro Motoki
-
Arkady.Kanevsky＠dell.com
-
Dmitry Tantsur
-
Iury Gregory
-
Jeremy Stanley
-
Luigi Toscano
-
Thomas Goirand