nextstrain / sphinx-theme

A Sphinx theme for Nextstrain's documentation, based on Read The Docs' default theme.

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

1. Make sure all your changes have been commited to the main branch.
2. Add a commit which describes the changes from the previous version to CHANGES.rst and updates the version number in lib/nextstrain/sphinx/theme/VERSION.
3. Tag this commit with the version number, e.g. git tag -a 2020.4 -m "version 2020.4".
4. Push the commit and tag to GitHub, e.g. git push origin main 2020.4.
5. Publish to PyPI by invoking a GitHub Actions workflow:
   1. Go to the workflow: publish.yml.
   2. Select Run workflow. In the new menu:
      1. Select Use workflow from > Tags > new version number (e.g. 2020.4).
      2. Set PyPI instance for publishing as PyPI (default) or TestPyPI. More info
      3. 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

sphinx-theme's Issues

toctree section headers (without index pages)

As @jameshadfield put it here:

I really want section headings (e.g. "Analysis" or "Getting started with analysis") to be simply headings in the sidebar, not pages in and of themselves. This holds for all our documentation on RTD, where we often have to create dummy pages with no real content.

According to @tsibley, this is possible: nextstrain/ncov#709 (comment).

Add John SJ

auto expand toctree sections

toctrees define the expandable sections in the sidebar navigation on read the docs. I think it's true in general that we would like these to be expanded by default to reveal the entries within them, rather than them being hidden by default.

See nextstrain/ncov#709 (comment), nextstrain/ncov#709 (comment)

Install nextstrain.sphinx.theme extension downstream

Upon seeing nextstrain/cli#198 I noticed we never leveraged #24 in practice across our docs projects.

• readthedocs-testbed: nextstrain/readthedocs-testbed#1
• nextstrain.org: nextstrain/nextstrain.org#574
• nextclade: nextstrain/nextclade#943
• cli: nextstrain/cli#198
• auspice: nextstrain/auspice#1535
• docs.nextstrain.org: nextstrain/docs.nextstrain.org#119
• augur: nextstrain/augur#1005
• ncov: nextstrain/ncov#983

Doing this would also automatically enable any other extensions we install here in the future.

Enable sphinx-copybutton extension by default

The sphinx-copybutton extension could be enabled by default for any doc project using this theme, leading to a more consistent click-to-copy of code blocks across all our Sphinx projects.

I believe the theme's setup(app) just needs to do:

app.setup_extension("sphinx_copybutton")

with sphinx-copybutton added to the theme's setup.py.

See also https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.setup_extension.

Context:

• nextstrain/ncov#904
• nextstrain/docs.nextstrain.org@cc2e2a8

Custom code-block colours

The current JSON code-fences use an unfortunate green/red colour combo, which I'd like to change!

The colours are defined in pygments.css. Unsure of the best approach to extending this / overwriting these in nextstrain.css but if someone could provide the framework I'll happily change some colours 😄

An example:

External link visual cue

Something similar to nextstrain.org/docs' symbols which indicate an external link in the sidebar (and in a document, but especially in the sidebar) would be helpful:

Update Fred Hutch logo

Footer badly formatted on all new builds

Current Behavior

The footer on new builds is improperly formatted (e.g. Augur 21.0.0 docs):

Expected behavior

The footer should look like this screenshot from the Augur 20.0.0 docs:

Explanation

This is due to the recent release of sphinx-rtd-theme 1.2.0 (specifically readthedocs/sphinx_rtd_theme@a039e52), which applies a grid layout to div.citation.

Possible solution

Rename/remove the citation class name. A quick inspection of the Augur 20.0.0 docs homepage doesn't reveal any styles applied using that class name. While I can't find explicit documentation anywhere, it seems that the citation class name is used by docutils and other projects to refer to footnote-style references as described in this issue.

Markdown heading levels incorrect

First noticed in nextstrain/docs.nextstrain.org#113 (comment):

In a markdown document, the number of # characters doesn't correspond to the HTML heading level.

For instance, in the above PR the main title is ## How data... but rendered as <h1>. Other headings are ##### [a1] Colorings but rendered as <h3>.

I presume this is addressed in this repo, but perhaps not?

Add Kim

Consider expanding references/citations in the footer

The current footer contains @jameshadfield et al., Bioinformatics 2018. We should probably include the @huddlej et al. Augur paper too. Are there other relevant papers to suggest for citation?

Additionally, consider providing and linking to a CITATION.cff or BibTeX file or similar containing the appropriate citations without manually transcribing them.