Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Bodhi's docs don't build with Sphinx 2.1.0 #3300

Closed
bowlofeggs opened this issue Jun 6, 2019 · 1 comment
Closed

Bodhi's docs don't build with Sphinx 2.1.0 #3300

bowlofeggs opened this issue Jun 6, 2019 · 1 comment
Labels
Crash Issues related to an unhandled crash Critical We can't go on living in this sqalor, drop everything and fix it! Docs Issues pertaining to Bodhi's documentation

Comments

@bowlofeggs
Copy link
Contributor

Due to Cornices/cornice.ext.sphinx#22 our autogenerated REST API docs won't build with Sphinx 2.1.0. I plan to pin us to Sphinx < 2.1 temporarily so that our pip CI tests will unblock our PRs, but we are going to have to solve this problem because eventually Rawhide is going to get that version of Sphinx and then we'll be in trouble.

Here are a few options we could consider:

  1. Fix cornice_sphinx. I have contributed a few patches before. I'm not sure how involved this fix will be.
  2. Switch to Django - there are a lot of benefits to doing this, but it is also a lot of work and we don't likely have the time to do it before Rawhide gets the new Sphinx (or before F31 is branched).
  3. Hand write our docs instead. We could use https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/ to assist in formatting, and we could also put the docs in-line in the Python service files. This would be a lot of work up front, and would also require us to maintain them as we change the API (which is why keeping them in-line in the Python code would be wise - that way we are more likely to remember to adjust them.)

Other ideas welcome.
@bowlofeggs bowlofeggs added Critical We can't go on living in this sqalor, drop everything and fix it! Docs Issues pertaining to Bodhi's documentation Crash Issues related to an unhandled crash labels Jun 6, 2019
bowlofeggs added a commit to bowlofeggs/bodhi that referenced this issue Jun 6, 2019
@bowlofeggs
Avoid sphinx >= 2.1 in the pip CI test
036de11 
Sphinx 2.1.0 does not work with cornice_sphinx[0]. This is causing
our CI to fail, but fixing it is not easy. For now, we are going
to install an older Sphinx until we can figure out what to do to
work with Sphinx >= 2.1.0.

re fedora-infra#3300

[0] Cornices/cornice.ext.sphinx#22

Signed-off-by: Randy Barlow <randy@electronsweatshop.com>
@bowlofeggs bowlofeggs mentioned this issue Jun 6, 2019
Merged
mergify bot pushed a commit that referenced this issue Jun 6, 2019
@bowlofeggs @mergify
Avoid sphinx >= 2.1 in the pip CI test
8e9d5c4 
Sphinx 2.1.0 does not work with cornice_sphinx[0]. This is causing
our CI to fail, but fixing it is not easy. For now, we are going
to install an older Sphinx until we can figure out what to do to
work with Sphinx >= 2.1.0.

re #3300

[0] Cornices/cornice.ext.sphinx#22

Signed-off-by: Randy Barlow <randy@electronsweatshop.com>
mattiaverga pushed a commit to mattiaverga/bodhi that referenced this issue Jun 10, 2019
@bowlofeggs @mattiaverga
Avoid sphinx >= 2.1 in the pip CI test
75ad1a6 
Sphinx 2.1.0 does not work with cornice_sphinx[0]. This is causing
our CI to fail, but fixing it is not easy. For now, we are going
to install an older Sphinx until we can figure out what to do to
work with Sphinx >= 2.1.0.

re fedora-infra#3300

[0] Cornices/cornice.ext.sphinx#22

Signed-off-by: Randy Barlow <randy@electronsweatshop.com>
@cverna cverna mentioned this issue Jul 11, 2019
Merged
@mattiaverga
Copy link
Contributor

This has been fixed, I forgot to close

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Crash Issues related to an unhandled crash Critical We can't go on living in this sqalor, drop everything and fix it! Docs Issues pertaining to Bodhi's documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@bowlofeggs @mattiaverga