docs.nextstrain.org

An umbrella documentation project for Nextstrain, hosted at docs.nextstrain.org, using:

• Read The Docs
• Sphinx
• Markdown and reStructuredText (quick ref, quicker ref)
• Subprojects for Augur, Auspice, Nextstrain CLI, Nextclade, etc.
• Our custom Sphinx theme to provide consistent, branded styling.

Domain / hosting management

To manage the hosting settings of docs.nextstrain.org and monitor automated builds triggered by pushes to this repository, go to https://readthedocs.org/projects/nextstrain/. You'll need to create a readthedocs.org account and be granted permissions to view and edit admin settings for the project by someone on the Nextstrain team.

Building the docs

Build dependencies are managed with Conda. Install them into an isolated environment named docs.nextstrain.org with:

conda env create --file conda.yml

Enter the environment with:

conda activate docs.nextstrain.org

You can now build the documentation with:

make html

which invokes Sphinx to build static HTML pages in build/html/. You can view them by running:

open build/html/index.html

To monitor the source files for changes and automatically rebuild as necessary, run:

make livehtml

and then open http://localhost:8000. Pages open in the browser will automatically refresh when they're rebuilt.

Leave the environment with:

conda deactivate

See below for how to build the docs for each subproject

Build configuration

Read The Docs

docs.nextstrain.org (the live version of the docs) is built and configured via the Read The Docs dashboard for this project. It uses our readthedocs.yml to get the right dependencies and configuration parameters to build the docs on the Read the Docs server; more about Read The Docs configuration.

You can adjust settings for the live version of the docs on the Read The Docs dashboard for this project. This includes:

Configuring redirects

Read The Docs supports user-defined redirects which we make use of when moving doc pages. Putting redirects in place ensures that people don't get lost when following saved links.

Redirects for this RTD project are exclusively defined in the redirects.yml file in this repo and synced to RTD using a GitHub Actions workflow. Syncing happens automatically on any push to master which changes the file. If you need to sync on demand, you can manually trigger a workflow run or run the rtd command in the workflow on your local machine.

A useful tip for Page redirects is that you may configure them while the From URL still is a valid page. This won't do anything until that page begins returning a 404, at which point the redirect will take effect. This can be helpful to test redirects on a branch/PR, where you can remove the page but still have it on the main branch of the repo. Your redirect will apply to the branch/PR version of the docs so long as the page has been removed in that version of the docs and the From URL in the redirect's configuration doesn't specify a version (such as in the example above). Then, upon merging the branch/PR, the redirect will apply in the same way on the merged version of the docs!

Sphinx

Sphinx is configured via src/conf.py; more about Sphinx configuration. This includes things like:

• Excluding files the building of the docs
• Specifying a custom Sphinx theme such as ours to provide consistent, branded styling.
• You may also run custom python code from this context which will execute at build time; we use this to fetch some remote documents.

Implementation

Document Formats

Markdown

Documents which don't need to include special table of contents or similar statements can be written in Markdown.

Markdown formatting reference.

reStructuredText

There are some set of special features of Sphinx / Read The Docs which require using reStructuredText, such as creating sidebar / table of contents entries with toctree statements (see File Hierarchy).

reStructuredText formatting reference.

Our convention for rST titles and sections is:

=====
Title
=====

Level 1
=======

Level 2
-------

Level 3
~~~~~~~

File Hierarchy

The hierarchy of the table of contents as seen in the sidebar can be thought of as a tree of documents. The root is src/index.rst a reStructuredText (see Restructured Text) file which dictates what the top-level headings in the sidebar will be. It contains multiple .. toctree:: "directive" or statements, followed by some configuration and then a list of file paths:

.. toctree::
    :maxdepth: 1
    :titlesonly:
    :caption: About
    :hidden:

    Introduction <self>
    learn/about
    learn/parts
    learn/interpret/index
    Pathogens <learn/pathogens/index>

These file paths (links to other documents) such as learn/interpret/index are what show up in the sidebar at the top level. If any file contains a valid one of these .. toctree:: statements, it will be rendered as an expandable heading in the sidebar, with the toctree entries rendered under that heading.

More on this in the Sphinx Documentation.

Subprojects

Subprojects are a way to nest Read The Docs projects.

We currently maintain the following subprojects for this project:

• Augur, sourced from https://github.com/nextstrain/augur/tree/master/docs
• Auspice, sourced from https://github.com/nextstrain/auspice/tree/master/docs
• Nextstrain CLI, sourced from https://github.com/nextstrain/cli/tree/master/doc
• Nextclade (includes Nextclade Web and Nextclade CLI), sourced from https://github.com/nextstrain/nextclade/tree/master/docs
• ncov (SARS-CoV-2 Workflow), sourced from https://github.com/nextstrain/ncov/tree/master/docs

To link to a file in a subproject (or any other Read The Docs project), use intersphinx, e.g.:

 ======================================
 Welcome to Nextstrain's documentation!
 ======================================

 Projects
 ========

+* :doc:`augur:index`

You also need to add the project you are linking to to the intersphinx configuration of your build.

How we are currently using subprojects

Subprojects are how we keep documents in other repositories while still maintaining the versioning of those documents from their own repositories in a separate Read The Docs project. Documents which we've kept in subprojects, as opposed to including them in this project, are usually specific reference material for those projects / repositories such as API documentation for augur. Another example is the tutorial for the SARS-CoV-2 workflow, which lives alongside the workflow in its repository, https://github.com/nextstrain/ncov, and shows up as a subproject at https://docs.nextstrain.org/projects/ncov/en/latest/index.html. Subprojects necessitate a distinct URL, such as https://docs.nextstrain.org/projects/augur as opposed to just https://docs.nextstrain.org. By default, this means a distinct set of headings / links in the sidebar navigation, making navigating back to https://docs.nextstrain.org more difficult once you have navigated to a subproject.

Building the Subproject docs

The documentation for each subproject is built from within the corresponding GitHub repo, also using sphinx.

For full details, see the respective how-to-build-docs sections:

• Augur
• Auspice
• Nextclade (includes Nextclade Web and Nextclade CLI)
• ncov (SARS-CoV-2 Workflow)

Fetching of documents from other repositories

Some documents are fetched from other repositories during the build process via src/fetch-docs.py, which is called from src/conf.py.

This setup is in lieu of a "best of both worlds" solution, which would allow us to version documents in subprojects accordi