Nextstrain Sphinx Theme
A Sphinx theme for Nextstrain’s documentation, based on Read The Docs’ default theme (sphinx_rtd_theme).
Installation
This theme is distributed on PyPI as nextstrain-sphinx-theme and can be
installed with pip
:
$ python3 -m pip install nextstrain-sphinx-theme
To use the theme in your Sphinx project, you will need to add the following to
your conf.py
file:
html_theme = "nextstrain-sphinx-theme"
This theme is based on sphinx_rtd_theme and accepts most of the same
configuration options settable via html_theme_option
and a few
additional options as well:
- logo:
Boolean determining if the Nextstrain logo should be displayed. Defaults to true.
- logo_link:
URL to use for the logo’s link. Defaults to <https://docs.nextstrain.org>.
- logo_only:
Ignored. Inherited from sphinx_rtd_theme. Instead, the project name and version info will not be displayed (thus showing only the logo) when
subproject
is true.- subproject:
Boolean determining if this is a subproject of the main Nextstrain documentation project on <https://docs.nextstrain.org>. Defaults to true.
If your project wants to display its own logo, just set Sphinx’s html_logo
to point to the image file in your Sphinx project.
html_logo = "_static/your-logo.png"
This will automatically take precedence over the default Nextstrain logo provided by the theme.
Development
python3 -m pip install -e .
make clean # not always needed, but better to be cautious
make html
open build/html/index.html
Releasing
Make sure all your changes have been commited to the
main
branch.Add a commit which describes the changes from the previous version to
CHANGES.rst
and updates the version number inlib/nextstrain/sphinx/theme/VERSION
.Tag this commit with the version number, e.g.
git tag -a 2020.4 -m "version 2020.4"
.Push the commit and tag to GitHub, e.g.
git push origin main 2020.4
.Publish to PyPI by invoking a GitHub Actions workflow:
Go to the workflow: publish.yml.
Select Run workflow. In the new menu:
Select Use workflow from > Tags > new version number (e.g. 2020.4).
Set PyPI instance for publishing as PyPI (default) or TestPyPI. More info
Select Run workflow.
Testing
PR test builds are available here: https://readthedocs.org/projects/nextstrain-sphinx-theme/builds/ and usually follow the following URL path convention: https://nextstrain–17.org.readthedocs.build/projects/sphinx-theme/en/17/ where 17 is the PR number