Update existing content

- Organizational changes:
    - Expose pages in main sidebar (6e35cdc)
    - Move pages to guides:
        - "Update the workflow" section from tutorial/setup -> guides/update-workflow
        - reference/customizing-analysis -> guides/workflow-config-file
        - reference/customizing-visualization -> guides/customizing-visualization
        - reference/data-prep -> guides/data-prep
            - Split "Data Prep" into 3 pages
    - Add reference/glossary
    - Rename reference files:
        - configuration -> workflow-config-file
        - orientation-files -> files
        - orientation-workflow -> nextstrain-overview
        - tutorial/running -> troubleshoot
    - Remove files:
        - reference/multiple_inputs
- Changes across multiple files:
    - Fix MD->reST conversion glitches
    - Reference "builds.yaml" as "workflow config file"
    - Remove my_profiles/ references
    - Reference glossary terms where appropriate
    - Use sphinx reference directive [1] to link to specific sections
- Per-file changes:
    - tutorial/setup
        - Remove basic example in setup page (replaced by the "example data" tutorial)
    - reference/gisaid-search
        - Remove off-topic line
    - reference/nextstrain-overview
        - Capitalize Augur, Auspice, Snakemake, Nextflow
        - Describe build vs. workflow
    - reference/files
        - Re-organize page with "user files" vs. "internal files"
    - reference/troubleshoot
        - Formerly tutorial/running, it has been stripped down to just troubleshooting content
    - dev_docs
        - Link to docs for installation/setup

[1]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations

defaults/description.md

@@ -1,5 +1,6 @@
-Hi! This is the default description. Edit me in `my_profiles/<build_name>/description.md`, and add this line to your `my_profiles/builds.yaml` file:  
-```
-files:  
-	description: my_profiles/<build_name>/description.md
+Hi! This is the default description, written in [Markdown](https://www.markdownguide.org/getting-started/). You can change this by creating another Markdown file and referencing it in the workflow config file:
+
+```yaml
+files:
+  description: path/to/description.md
 ```

docs/dev_docs.md

@@ -7,53 +7,9 @@
  1. [Running](#running)
  1. [Releasing new workflow versions](#releasing-new-workflow-versions)
 
-## Setup
-
-Please see [the main Nextstrain docs](https://nextstrain.org/docs/getting-started/introduction#open-source-tools-for-the-community) for instructions for installing the Nextstrain bioinformatics pipeline (Augur) and visualization tools (Auspice).
-
-## Data
-
-In order to run the Nextstrain build you must provision `./data/sequences.fasta` and `./data/metadata.tsv`.
-We've included a test set of sequences that are publicly available via Genbank as `./example_data/sequences.fasta`.
-
 ## Running
 
-Please see [these docs](./docs/running.md) for instructions on how to run this build yourself.
-
-The resulting output JSON at `auspice/ncov.json` can be visualized by running `auspice view --datasetDir auspice` or `nextstrain view auspice/` depending on local vs containerized installation.
-
-### Finalizing automated builds
-
-To run a regional build, be sure to update the list of regions in `nextstrain_profiles/nextstrain-gisaid/builds.yaml`.
-You can run all builds in parallel with the following command.
-
-```bash
-snakemake --profile nextstrain_profiles/nextstrain-gisaid all_regions
-```
-
-Or you can specify final or intermediate output files like so:
-
-```bash
-# subsampled regional focal
-snakemake --profile nextstrain_profiles/nextstrain-gisaid auspice/ncov_europe.json
-
-# subsampled global
-snakemake --profile nextstrain_profiles/nextstrain-gisaid auspice/ncov_global.json
-```
-
-To update ordering/lat_longs after AWS download:
-
-```bash
-snakemake --touch --forceall --profile nextstrain_profiles/nextstrain-gisaid
-snakemake --profile nextstrain_profiles/nextstrain-gisaid clean_export_regions
-snakemake --profile nextstrain_profiles/nextstrain-gisaid export_all_regions
-```
-
-When done adjusting lat-longs & orders, remember to run the following command to produce the final Auspice files.
-
-```bash
-snakemake --profile nextstrain_profiles/nextstrain-gisaid all_regions
-```
+Visit [the workflow documentation](https://docs.nextstrain.org/projects/ncov) for instructions on how to set up and run the workflow.
 
 ## Releasing new workflow versions
 

docs/redirects.yml

@@ -14,27 +14,27 @@
 
 - type: page
   from_url: /analysis/customizing-analysis.html
-  to_url: /reference/customizing-analysis.html
+  to_url: /guides/workflow-config-file.html
 
 - type: page
   from_url: /analysis/customizing-visualization.html
-  to_url: /reference/customizing-visualization.html
+  to_url: /guides/customizing-visualization.html
 
 - type: page
   from_url: /analysis/data-prep.html
-  to_url: /guides/data-prep.html
+  to_url: /guides/data-prep/index.html
 
 - type: page
   from_url: /analysis/orientation-files.html
-  to_url: /reference/orientation-files.html
+  to_url: /reference/files.html
 
 - type: page
   from_url: /analysis/orientation-workflow.html
-  to_url: /reference/orientation-workflow.html
+  to_url: /reference/nextstrain-overview.html
 
 - type: page
   from_url: /analysis/running.html
-  to_url: /tutorial/running.html
+  to_url: /reference/troubleshoot.html
 
 - type: page
   from_url: /analysis/setup.html
@@ -43,3 +43,19 @@
 - type: page
   from_url: /videos.html
   to_url: /tutorial/videos.html
+
+- type: page
+  from_url: /reference/configuration.html
+  to_url: /reference/workflow-config-file.html
+
+- type: page
+  from_url: /reference/multiple_inputs.html
+  to_url: /
+
+- type: page
+  from_url: /visualization/index.html
+  to_url: /visualization/sharing.html
+
+- type: page
+  from_url: /guides/index.html
+  to_url: /guides/run-analysis-on-terra.html

docs/src/_static/css/configuration-parameters.css → docs/src/_static/css/configuration-reference.css

@@ -1,5 +1,5 @@
-/* Custom CSS to be applied to the reference/configuration.rst
-   page. That page defines a customclass of .configurationparameters */
+/* Custom CSS to be applied to the reference/workflow-config-file.rst
+   page. That page defines a custom class of .configuration-reference */
 
 
 /* We detail a lot of nested (snakemake) configuration entries in the
@@ -9,21 +9,21 @@ The following style changes are intended to convey that certain config
 entries are children of a higher-level config, rather than being top-level
 config parameters themselves */
 
-.configurationparameters h4 {
+.configuration-reference h4 {
     font-size: 100%;
 }
 
 /* Pad lists generated by a (local) contents directive showing sub-keys */
-.configurationparameters section > section > div.contents.local.topic {
+.configuration-reference section > section > div.contents.local.topic {
     margin-left: 24px; /* same as a nested <li> */
     margin-top: -20px; /* CSS can't select previous sibling, FYI */
 }
-.configurationparameters section > section > div.contents.local.topic > ul > li {
+.configuration-reference section > section > div.contents.local.topic > ul > li {
     list-style: circle;
 }
 /* pad out their siblings (which come _after_ the list) so that they
    are in line with the start of text in the preceding <li> element */
-.configurationparameters section > section > div.contents.local.topic ~ * {
+.configuration-reference section > section > div.contents.local.topic ~ * {
     margin-left: 48px; 
 }
 

docs/src/conf.py

@@ -102,7 +102,7 @@ def prose_list(items):
 # or fully qualified paths (eg. https://...)
 html_css_files = [
     'css/custom.css',
-    'css/configuration-parameters.css'
+    'css/configuration-reference.css'
 ]
 
 # -- Cross-project references ------------------------------------------------

docs/src/guides/customizing-visualization.rst

@@ -0,0 +1,111 @@
+Customizing visualization
+=========================
+
+Visualization options can be configured in either a :term:`workflow config file<config file>` or a :term:`Auspice config file`, depending on the option.
+
+.. contents:: Table of Contents
+   :local:
+
+Options in the workflow config file
+-----------------------------------
+
+These options can be coded into the workflow config file directly without requiring a custom Auspice config file.
+
+Custom color schemes
+~~~~~~~~~~~~~~~~~~~~
+
+To specify a custom color scale:
+
+1. Add a ``colors.tsv`` file, where each line is a tab-delimited list of a metadata column name; a metadata value; and a corresponding hex code. Example:
+
+   ::
+
+      country Russia  #5E1D9D
+      country Serbia  #4D22AD
+      country Europe  #4530BB
+      ...
+
+2. Update your workflow config file with a reference:
+
+   .. code:: yaml
+
+      files:
+        colors: "my-ncov-analyses/colors.tsv"
+
+Changing the dataset description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The dataset description, which appears below the visualizations, is read from a file which is specified in the workflow config file. Per-build description can be set by specifying them in the workflow config file:
+
+.. code:: yaml
+
+   builds:
+     north-america: # name of the build
+       description: my-ncov-analyses/north-america-description.md
+
+If that is not provided, then a per-run description is used, also specified in the workflow config file:
+
+.. code:: yaml
+
+   files:
+     description: my-ncov-analyses/my_description.md
+
+Options in the Auspice config file
+----------------------------------
+
+These options require creating an Auspice config file, used to configure :term:`docs.nextstrain.org:Auspice`. It is specified in the workflow config file using the ``auspice_config`` entry. Example:
+
+.. code:: yaml
+
+   auspice_config: ncov-tutorial/auspice-config-custom-data.json
+
+This overrides the default Auspice config file, ``defaults/auspice_config.json``.
+
+Adding custom metadata fields to color by
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Add a :doc:`valid metadata column <./data-prep/local-data>` to your ``metadata.tsv``
+2. Add an entry to the ``colorings`` block of the Auspice config file:
+
+   .. code:: json
+
+      "colorings": [
+      {
+         "key": "location",
+         "title": "Location",
+         "type": "categorical"
+      },
+      {
+         "key": "metadata_column_name",
+         "title": "Display name for interface",
+         "type": "<categorical/continuous>"
+      }
+      ]
+
+Choosing defaults
+~~~~~~~~~~~~~~~~~
+
+You can specify the default view in the ``display_defaults`` block of an Auspice config file:
+
+.. code:: json
+
+   "display_defaults": {
+     "color_by": "division",
+     "distance_measure": "num_date",
+     "geo_resolution": "division",
+     "map_triplicate": true,
+     "branch_label": "none"
+   },
+
+Choosing panels to display
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Similarly, you can choose which panels to enable in the ``panels`` block:
+
+.. code:: json
+
+   "panels": [
+     "tree",
+     "map",
+     "entropy"
+   ]