search

nextstrain / docs.nextstrain.org

Umbrella documentation project for Nextstrain
https://docs.nextstrain.org
18 stars 13 forks source link

readme

docs.nextstrain.org

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

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

Building the docs with Docker

Alternatively, you can perform the same steps inside a container.

Once you have Docker installed, run:

make docker-html

The HTML files appear in build/html/ as usual, and can be viewed in a browser.

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:

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:

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:

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 according to their own repositories, and also include them in this project's domain and table of contents without having to navigate to a separate project to view them.

We aim to make this a temporary solution until we can achieve a shared-table-of-contents approach alluded to above; see https://github.com/nextstrain/docs.nextstrain.org/issues/27.

Files fetched are excluded from git tracking in .gitignore so they don't get added to this repo by mistake. They should be edited in their own repositories. When editing those files in their respective repositories, keep in mind that any relative paths to images or other documents need to exist in this repository's file structure where the fetched file ends up.

Contributing

How to edit a document

Every document on docs.nextstrain.org and in the subprojects should have a link in the top right corner of the page that says "Edit on GitHub":

Screen Shot 2021-10-05 at 3 44 06 PM

Clicking this will take you to the repository on GitHub for that document so that you know what file to change to edit that document.

Pushing changes to the file on the main branch of that repository will automatically rebuild the documentation with your changes, but if you're not sure of the changes and want to see the result, it's best to build the documentation locally.

You can push your changes up to a new branch and then activate automatic builds of that branch by finding it on https://readthedocs.org/projects/nextstrain/versions/ and clicking "Activate".

How to add a document

  1. What type of document is it? This will help write it with a clear goal in mind.
  2. Where should it go in the table of contents? See the Table of Contents at https://docs.nextstrain.org/en/latest/ to find a heading that fits the document best.
  3. Once the document is written, move it to the directory corresponding to the heading under which you'd like to to appear, e.g.: 
    mv interacting-with-nextstrain.md src/learn/interpret/

  4. Add a relative path to the document file to a toctree, e.g. src/learn/interpret/index.rst:

    ======================================
Interpreting Nextstrain
======================================

Learn how to interpret Nextstrain analyses.

.. toctree::
:maxdepth: 2
:titlesonly:
:caption: Table of contents

how-to-read-a-tree
+   interacting-with-nextstrain
Interpreting the Map <map-interpretation>
  5. Build the docs to see it rendered, and make any necessary edits before pushing to this repo.

How-to tips

If you come across a useful feature to solve a common problem in the docs implementation, add it here!

Hide table of contents; only display in the sidebar

Adding the following line to the table of contents statement in the index / root page of this project, for example, will remove the table of contents section from that document and only render the table of contents in the navigation bar on the left like this:

 .. toctree::
    :maxdepth: 2
    :titlesonly:
+   :hidden:
    :caption: Table of contents

    self
    learn/index
    tutorials/index
    guides/index
    reference/index

Types of documents

In terms of the content of a given document, we aim to classify documents according to the Documentation System. The Documentation System makes clear the distinction between motivations for different types of docs. It advocates for a balance of content from these distinct categories for more useful docs experience by doc readers and a more well-defined task for doc writers. Explicitly spelling out this breakdown in the docs themselves is recommended to make choosing the right document for a given question more transparent.

The types of documents are: