Merge pull request #1091: Update tutorial docs

docs/Makefile

@@ -19,6 +19,9 @@ help:
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+livehtml:
+	sphinx-autobuild -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
 .ONESHELL:
 docker-html:
 	set -euox

docs/README.md

@@ -22,6 +22,15 @@ 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.
+
 You can clean the build directory for a fresh start with:
 
     make clean

docs/conda.yml

@@ -11,6 +11,7 @@ dependencies:
     - sphinx
     - docutils<0.18
     - sphinx-argparse
+    - sphinx-autobuild
     - sphinx-copybutton
     - sphinx-markdown-tables
     - sphinx-tabs

docs/src/conf.py

@@ -16,10 +16,8 @@
 
 
 # -- Project information -----------------------------------------------------
-from datetime import date, timedelta
-from docutils import nodes
-from docutils.parsers import rst
-from docutils.parsers.rst import directives
+
+from datetime import date
 import subprocess
 
 def git_authors():
@@ -115,40 +113,3 @@ def prose_list(items):
     'auspice': ('https://docs.nextstrain.org/projects/auspice/en/stable', None),
     'snakemake': ('https://snakemake.readthedocs.io/en/stable', None),
 }
-
-# Custom directives.
-class TimeDeltaDirective(rst.Directive):
-    """Minimal directive to call datetime.timedelta with the given optional
-    arguments and return today's date plus the calculated delta. If no arguments
-    are provided, returns today's date. All dates are formatted in ISO-8601
-    standard of %Y-%m-%d.
-
-    """
-    required_arguments = 0
-    optional_arguments = 7
-
-    option_spec = {
-        "days": directives.unchanged,
-        "seconds": directives.unchanged,
-        "microseconds": directives.unchanged,
-        "milliseconds": directives.unchanged,
-        "minutes": directives.unchanged,
-        "hours": directives.unchanged,
-        "weeks": directives.unchanged,
-    }
-
-    def run(self):
-        kwargs = {}
-        for option in self.option_spec.keys():
-            if option in self.options:
-                kwargs[option] = int(self.options[option])
-
-        date_object = date.today()
-        if kwargs:
-            date_object = date_object + timedelta(**kwargs)
-
-        date_text = date_object.strftime("%Y-%m-%d")
-
-        return [nodes.Text(date_text)]
-
-directives.register_directive("timedelta", TimeDeltaDirective)

docs/src/reference/glossary.rst

@@ -14,9 +14,9 @@ Glossary
       A JSON file used to configure visualization in :term:`docs.nextstrain.org:Auspice`.
 
    config file
-      also *workflow configuration file*, ``builds.yaml``
+      also *workflow config file*, *workflow configuration file*, ``builds.yaml``
 
-      A YAML file used for :term:`Snakemake`'s ``--configfile`` parameter. Appends to and overrides default configuration in ``defaults/parameters.yaml``.
+      A YAML file used to `configure <https://snakemake.readthedocs.io/en/stable/snakefiles/configuration.html#standard-configuration>`__ the :term:`Snakemake` workflow (via the ``--configfile`` option). Appends to and overrides default configuration in ``defaults/parameters.yaml``. For the :term:`ncov workflow`, this file must follow a :doc:`specific format <workflow-config-file>`.
 
    customization file
 

docs/src/tutorial/custom-data.rst

@@ -85,7 +85,7 @@ We will retrieve 10 sequences from GISAID's EpiCoV database.
 Run the workflow
 ----------------
 
-From within the ``ncov/`` directory, run the ``ncov`` workflow using a pre-written ``--configfile``:
+From within the ``ncov/`` directory, run the ``ncov`` workflow using a pre-written :term:`config file`:
 
 .. code:: text
 

docs/src/tutorial/example-data.rst

@@ -43,10 +43,10 @@ Break down the command
 The workflow can take several minutes to run. While it is running, you can learn about the parts of this command:
 
 - ``nextstrain build .``
-   - This tells the :term:`docs.nextstrain.org:Nextstrain CLI` to :term:`build <docs.nextstrain.org:build (verb)>` the workflow from ``.``, the current directory. All subsequent command-line parameters are passed to the workflow manager, Snakemake.
+   - This tells the :term:`docs.nextstrain.org:Nextstrain CLI` to :term:`build <docs.nextstrain.org:build (verb)>` the workflow from ``.``, the current directory. All subsequent command-line arguments are passed to the workflow manager, Snakemake.
 - ``--configfile ncov-tutorial/example-data.yaml``
-   - ``--configfile`` is another Snakemake parameter used to configure the ncov workflow.
-   - ``ncov-tutorial/example-data.yaml`` is a configuration file that provides custom workflow configuration including inputs and outputs. The contents of this file with comments excluded are:
+   - ``--configfile`` is a Snakemake option used to `configure <https://snakemake.readthedocs.io/en/stable/snakefiles/configuration.html#standard-configuration>`__ the ncov workflow. It takes a file path as the value.
+   - ``ncov-tutorial/example-data.yaml`` is the value given to ``--configfile``. It is a :term:`config file` that provides custom workflow configuration including inputs and outputs. The contents of this file with comments excluded are:
 
       .. code-block:: yaml
 
@@ -64,7 +64,10 @@ The workflow can take several minutes to run. While it is running, you can learn
 
       For more information, :doc:`see the workflow configuration file reference <../reference/workflow-config-file>`.
 
-The workflow output produces a new directory ``auspice/`` containing a file ``ncov_default-build.json``, which will be visualized in the following section. The workflow also produces intermediate files in a new ``results/`` directory.
+Running the workflow produces two new directories:
+
+- ``auspice/`` contains a few files that represent a Nextstrain :term:`docs.nextstrain.org:dataset` to be visualized in the following section.
+- ``results/`` contains intermediate files generated during workflow execution.
 
 Visualize the results
 ---------------------

docs/src/tutorial/genomic-surveillance.rst

@@ -39,27 +39,20 @@ We will download a focal set of Idaho sequences from GISAID's EpiCoV database.
       :width: 400
       :alt: GISAID EpiCoV Search
 
-.. |last-month| timedelta::
-   :weeks: -4
-
-.. |today| date::
-
 2. Filter to sequences that pass the following criteria:
 
-   1. From Idaho, USA
-   2. Collected within the last month (e.g. |last-month| to |today|)
+   1. From North America / USA / Idaho
+   2. Collected between 2022-03-01 and 2022-04-01
    3. Has a complete genome
    4. Has an exact collection date
 
    .. figure:: ../images/gisaid-select-sequences-idaho-highlighted.png
       :width: 700
       :alt: GISAID EpiCoV filter and select sequences
 
-      Example of GISAID filters using collection date between 2022-03-01 and 2022-04-01
-
    .. note::
 
-      If your selection has more than 200 sequences, adjust the minimum date until it has 200 sequences or less. This ensures the tutorial does not take too long to run.
+      If your selection has more than 250 sequences, adjust the minimum date until it has 250 sequences or less. This ensures the tutorial does not take too long to run.
 
 3. Select the topmost checkbox in the first column to select all sequences that match the filters.
 4. Select **Download** > **Input for the Augur pipeline** > **Download**.
@@ -72,7 +65,7 @@ We will download a focal set of Idaho sequences from GISAID's EpiCoV database.
 Run the workflow
 ----------------
 
-From within the ``ncov/`` directory, run the ``ncov`` workflow using a pre-written ``--configfile``:
+From within the ``ncov/`` directory, run the ``ncov`` workflow using a pre-written :term:`config file`:
 
 .. code:: text
 
@@ -168,7 +161,7 @@ Run this command to start the :term:`docs.nextstrain.org:Auspice` server, provid
 
    nextstrain view auspice/
 
-Navigate to http://127.0.0.1:4000/ncov/idaho. The resulting :term:`docs.nextstrain.org:dataset` should show the recent Idaho sequences against a backdrop of historical sequences:
+Navigate to http://127.0.0.1:4000/ncov/idaho. The resulting :term:`docs.nextstrain.org:dataset` should show the Idaho sequences against a backdrop of historical sequences:
 
 .. figure:: ../images/dataset-genomic-surveillance.png
    :alt: Phylogenetic tree from the "genomic surveillance" tutorial as visualized in Auspice