improving usability of lower-left rtd menu #983
Conversation
This commit makes several changes to the rtd theme's version.html template such that the lower-left rtd menu now has: 1. Support to display nav links to alternate languages by defining them as a list of tuples (just like versions and downloads) 2. Adds a new variable 'display_lower_left' so that the lower-left menu can be toggled independently, while the "On Read the Docs" section is toggled with the READTHEDOCS boolean. 3. Adds a conditional to the 'versions' section to display the current version in bold (same as readthedocs.io does) 4. Add a conditional to the 'downloads' section to only display the downloads section if there's a non-empty downloads list For more information about this change, see: * https://tech.michaelaltfield.net/2020/07/23/sphinx-rtd-github-pages-2/
|
These changes make sense not sure if it conflicts in any way with Read the docs. |
| @@ -1,4 +1,4 @@ | |||
| {% if READTHEDOCS %} | |||
| {% if READTHEDOCS or display_lower_left %} | |||
| {# Add rst-badge after rst-versions for small badge style. #} | |||
| <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions"> | |||
| <span class="rst-current-version" data-toggle="rst-current-version"> | |||
There was a problem hiding this comment.
I think this should only be displayed on readthedocs
There was a problem hiding this comment.
@Blendify I'm not sure exactly what this comment means. The whole purpose of this PR is to add the ability to display the lower-left menu when not on readthedocs.
By default, it will not be displayed. If the user specifies html_context['display_lower_left'] = True in their sphinx config (or it is in-fact readthedocs), then it is displayed. This is not an uncommon desired functionality. See:
- https://stackoverflow.com/questions/49331914/enable-versions-in-sidebar-in-sphinx-read-the-docs-theme
- https://tech.michaelaltfield.net/2020/07/23/sphinx-rtd-github-pages-2/
This has been tested by the way, and you can see my changes downstream in-action at the following websites:
- https://docs.buskill.in/
- https://vienneae.github.io/rtd-github-pages/
- https://nicozanf.github.io/py4web-doc/
This PR was created to push these changes back upstream so it would benefit the rest of the community.
There was a problem hiding this comment.
This makes sense to me as well. This is mainly used at rtd like a "default" or "fallback" (and it only contains the versions at the moment that the build happened), the final footer (with all the current versions/translations) is injected with this content https://github.com/readthedocs/readthedocs.org/blob/master/readthedocs/api/v2/templates/restapi/footer.html (in case if that fails the user can still navigate the default one).
I think we should document this variables
This commit makes several changes to the rtd theme's version.html template such that the lower-left rtd menu now has:
Support to display nav links to alternate languages by defining them as a list of tuples (just like versions and downloads)
Adds a new variable 'display_lower_left' so that the lower-left menu can be toggled independently, while the "On Read the Docs" section is toggled with the READTHEDOCS boolean.
Adds a conditional to the 'versions' section to display the current version in bold (same as readthedocs.io does)
Add a conditional to the 'downloads' section to only display the downloads section if there's a non-empty downloads list
For more information about this change, see: