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.

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

Update sphinx and furo while removing "Edit on GitHub" hack in the process #4341

Merged
merged 6 commits into from Jan 15, 2024

Conversation

joshuacwnewton
Copy link
Member

@joshuacwnewton joshuacwnewton commented Jan 15, 2024

Description

When installing sphinx via pip install sphinx, it depends on a number of extensions (including sphinxcontrib-applehelp):

(venv_sct) jn/4340-update-sphinx|joshua@monarch:~/repos/spinalcordtoolbox$ pip show sphinx
Name: Sphinx
Version: 4.5.0
Summary: Python documentation generator
Home-page: https://www.sphinx-doc.org/
Author: Georg Brandl
Author-email: georg@python.org
License: BSD
Location: /home/joshua/repos/spinalcordtoolbox/python/envs/venv_sct/lib/python3.9/site-packages
Requires: alabaster, babel, docutils, imagesize, importlib-metadata, Jinja2, packaging, Pygments, requests, snowballstemmer, sphinxcontrib-applehelp, sphinxcontrib-devhelp, sphinxcontrib-htmlhelp, sphinxcontrib-jsmath, sphinxcontrib-qthelp, sphinxcontrib-serializinghtml

The newest version of sphinxcontrib-applehelp requires sphinx>=5.0, yet we're currently pinning sphinx to a 4.x version, which causes the RTD build to fail.

Additionally, we're pinning a 2021 version of furo (presumably to avoid upstream versions unexpectedly changing the appearance of our docs), which also pins an old version of sphinx. So, we need to update furo as well if we want to update sphinx.

In turn, updating sphinx and furo require some additional changes:

  • language = None now triggers a warning, so change to 'en'
  • extlinks now requires explicitly using %s in the caption instead of ''
  • Our old "Edit on GitHub" button hack is no longer needed, as furo now provides this function natively, so we can remove the relevant files. (This fixes one of @jcohenadad's concerns, where the "Edit" button had a confusing logo -- now it's a pencil.)

Linked issues

Fixes #4340.

`furo` now supports this natively (with a more suitable icon!!), so we no longer need to override furo's built-in page templates.
@joshuacwnewton joshuacwnewton added the documentation category: readthedocs, sourceforge, or SCT courses label Jan 15, 2024
@joshuacwnewton joshuacwnewton added this to the 6.2 milestone Jan 15, 2024
@joshuacwnewton joshuacwnewton self-assigned this Jan 15, 2024
Copy link
Member

@mguaypaq mguaypaq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks very reasonable. Thanks for the fix and update!

@joshuacwnewton joshuacwnewton merged commit 1a5fa87 into master Jan 15, 2024
24 checks passed
@joshuacwnewton joshuacwnewton deleted the jn/4340-update-sphinx branch January 15, 2024 18:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation category: readthedocs, sourceforge, or SCT courses
Projects
None yet
Development

Successfully merging this pull request may close these issues.

RTD build failing
2 participants