nextstrain · genehack · Aug 15, 2024 · Aug 9, 2024 · Aug 9, 2024 · Aug 9, 2024
diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -113,3 +113,35 @@ def prose_list(items):
     'auspice': ('https://docs.nextstrain.org/projects/auspice/en/stable', None),
     'snakemake': ('https://snakemake.readthedocs.io/en/stable', None),
 }
+
+# -- Linkchecking ------------------------------------------------------------
+
+linkcheck_ignore = [
+    # we have links to localhost for explanatory purposes; obviously
+    # they will never work in the linkchecker
+    r'^http://127\.0\.0\.1:\d+',
+    r'^http://localhost:\d+',
+    # the top level bucket link 404s
+    r'^https://data\.nextstrain\.org$',
+    # they block the client, probably anti-scraping measure
+    r'^https://czgenepi\.org/resources',
+    r'^https://science\.sciencemag\.org/content/early/2020/06/05/science\.abb9263',
+    # this link is correct but the lack of a top-level dataset means
+    # it 404s initially — because the point of this link is showing
+    # the community page, allow it to fail here:
+    r'^https://nextstrain\.org/community/ESR-NZ/GenomicsNarrativeSARSCoV2$'
+]
+linkcheck_anchors_ignore_for_url = [
+    # Github uses anchor-looking links for highlighting lines but
+    # handles the actual resolution with Javascript, so skip anchor
+    # checks for Github URLs:
+    r'^https://github\.com',
+    # you need to be logged in to see the anchor (and it looks like
+    # Terra is using it for redirecting more than anchoring too…)
+    r'^https://app\.terra\.bio/',
+    # client is blocked but links work
+    r'^https://www\.science\.org/doi/10\.1126/science\.abb9263',
+    # linkchecker doesn't support text fragments, and we link to one
+    # anchored to this page
+    r'^https://en\.wikipedia\.org/wiki/Consensus_sequence',
+]
diff --git a/docs/src/guides/data-prep/gisaid-search.rst b/docs/src/guides/data-prep/gisaid-search.rst
@@ -9,7 +9,7 @@ The following instructions describe how to curate data for a region-specific ana
 Login to GISAID
 ---------------
 
-Navigate to `GISAID (gisaid.org) <https://www.gisaid.org/>`__ and select the “Login” link.
+Navigate to `GISAID (gisaid.org) <https://gisaid.org/>`__ and select the “Login” link.
 
 .. figure:: ../../images/gisaid-homepage.png
    :alt: GISAID homepage with login link

diff --git a/docs/src/guides/update-workflow.rst b/docs/src/guides/update-workflow.rst
@@ -5,7 +5,7 @@ We update the official workflow regularly with:
 
 -  `curated metadata including latitudes/longitudes, clade annotations, and low quality sequences <https://github.com/nextstrain/ncov/commits/master>`__
 -  bug fixes
--  `new features <../reference/change_log>`__
+-  :doc:`new features <../reference/change_log>`
 
 Update your local copy of the workflow, to benefit from these changes.
 
@@ -21,7 +21,7 @@ Update your local copy of the workflow, to benefit from these changes.
    # and then replay your local changes on top of those incoming changes.
    git pull --rebase origin master
 
-Alternately, download a specific version of the workflow that you know works for you. We create new `releases of the workflow <https://github.com/nextstrain/ncov/releases/>`__ any time we introduce breaking changes, so you can choose when to update based on `what has changed <../reference/change_log>`__.
+Alternately, download a specific version of the workflow that you know works for you. We create new `releases of the workflow <https://github.com/nextstrain/ncov/releases/>`__ any time we introduce breaking changes, so you can choose when to update based on :doc:`what has changed <../reference/change_log>`.
 
 .. code:: bash
 

diff --git a/docs/src/reference/change_log.md b/docs/src/reference/change_log.md
@@ -107,7 +107,7 @@ We also use this change log to document new features that maintain backward comp
 
 ## New features since last version update
 
- - 11 August 2021: Add support for "Sequences" and "Patient status metadata" downloads from GISAID's search interface including [documentation in the tutorial of how to use these data](../guides/data-prep.html#curate-data-from-gisaid-search-and-downloads). ([#701](https://github.com/nextstrain/ncov/pull/701))
+ - 11 August 2021: Add support for "Sequences" and "Patient status metadata" downloads from GISAID's search interface including [documentation in the tutorial of how to use these data](https://docs.nextstrain.org/projects/ncov/en/latest/guides/data-prep/gisaid-search.html). ([#701](https://github.com/nextstrain/ncov/pull/701))
  - 6 August 2021: We've replaced the mechanisms that support remote file inputs (e.g. `s3://` URLs) to improve internal workflow structure, extend support to `gs://`, `http://`, and `https://` URLs, and expand support for compressed inputs.
    Our [remote file inputs documentation](remote_inputs) is updated to reflect the changes.
 
@@ -128,7 +128,7 @@ We also use this change log to document new features that maintain backward comp
 
 ## v7 (27 May 2021)
 
-For more details about this release, see [the configuration reference for the new "sanitize metadata" parameters](configuration.html#sanitize_metadata) and [the corresponding pull request](https://github.com/nextstrain/ncov/pull/640).
+For more details about this release, see [the configuration reference for the new "sanitize metadata" parameters](https://docs.nextstrain.org/projects/ncov/en/latest/reference/workflow-config-file.html#sanitize-metadata) and [the corresponding pull request](https://github.com/nextstrain/ncov/pull/640).
 
 ### Major changes
 
@@ -141,7 +141,7 @@ For more details about this release, see [the configuration reference for the ne
 
 ## New features since last version update
 
- - 25 May 2021: Support custom Auspice JSON prefixes with a new configuration parameter, `auspice_json_prefix`. [See the configuration reference for more details](configuration.html#auspice_json_prefix). ([#643](https://github.com/nextstrain/ncov/pull/643))
+ - 25 May 2021: Support custom Auspice JSON prefixes with a new configuration parameter, `auspice_json_prefix`. [See the configuration reference for more details](https://docs.nextstrain.org/projects/ncov/en/latest/reference/workflow-config-file.html#auspice-json-prefix). ([#643](https://github.com/nextstrain/ncov/pull/643))
 
 ## v6 (20 May 2021)
 
@@ -161,7 +161,7 @@ For more details about this release, see [the configuration reference for the ne
 
 ### Major changes
 
-- Drop support for old sequence/metadata inputs. This change removes support for the `config["sequences"]` and `config["metadata"]` starting points for the workflow in favor of the more flexible [`config["inputs"]` format](configuration.html#inputs).
+- Drop support for old sequence/metadata inputs. This change removes support for the `config["sequences"]` and `config["metadata"]` starting points for the workflow in favor of the more flexible [`config["inputs"]` format](https://docs.nextstrain.org/projects/ncov/en/latest/reference/workflow-config-file.html#inputs).
 - Use `nextalign` for alignment instead of `mafft`. This change completely removes support for `mafft` in favor of `nextalign`. Future versions may reinstate `mafft` support as part of `augur align` updates.
 
 ### Minor changes
@@ -188,7 +188,7 @@ For more details about this release, see [the configuration reference for the ne
 
 ## New features since last version update
 
-- 20 April 2021: Surface emerging lineage as a colorby. This replaces the rather stale color by "Emerging Clade" with a new color by "Emerging Lineage". This focuses on PANGO lineages that are of interest triangulated by [CoVariants](https://covariants.org/), [PANGO](https://cov-lineages.org/) international lineage reports, [CDC](https://www.cdc.gov/coronavirus/2019-ncov/cases-updates/variant-surveillance/variant-info.html) VUIs and VOCs and [PHE](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/975742/Variants_of_Concern_VOC_Technical_Briefing_8_England.pdf) VUIs and VOCs. The intention is for the listing at `emerging_lineages.tsv` to be updated frequently with new lineages added and no longer interesting lineages dropped. [#609](https://github.com/nextstrain/ncov/pull/609)
+- 20 April 2021: Surface emerging lineage as a colorby. This replaces the rather stale color by "Emerging Clade" with a new color by "Emerging Lineage". This focuses on PANGO lineages that are of interest triangulated by [CoVariants](https://covariants.org/), [PANGO](https://cov-lineages.org/) international lineage reports, [CDC](https://www.cdc.gov/covid/php/variants/index.html) VUIs and VOCs and [PHE](https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/975742/Variants_of_Concern_VOC_Technical_Briefing_8_England.pdf) VUIs and VOCs. The intention is for the listing at `emerging_lineages.tsv` to be updated frequently with new lineages added and no longer interesting lineages dropped. [#609](https://github.com/nextstrain/ncov/pull/609)
 
 - 12 April 2021: Calculate current clade frequency and logistic growth rate across nodes in the phylogeny. This produces a new `logistic_growth.json` file and uses this file to add a coloring the final Auspice JSON. Implementation choices are discussed in PR [#595](https://github.com/nextstrain/ncov/pull/595).
 

diff --git a/docs/src/reference/metadata-fields.rst b/docs/src/reference/metadata-fields.rst
@@ -21,7 +21,7 @@ Name of the pathogen.
 Column 3: ``gisaid_epi_isl``
 --------------------------------------
 
-If this genome is shared via `GISAID <https://www.gisaid.org/>`__ then please include the EPI ISL here. In our example this is ``EPI_ISL_413490``.
+If this genome is shared via `GISAID <https://gisaid.org/>`__ then please include the EPI ISL here. In our example this is ``EPI_ISL_413490``.
 
 Column 4: ``genbank_accession``
 --------------------------------------
@@ -112,12 +112,12 @@ Sex of the patient from whom the sample was collected. This will show up in ausp
 Column 18: ``originating_lab``
 --------------------------------------
 
-Please see `GISAID <https://www.gisaid.org/help/publish-with-gisaid-references/>`__ for more information.
+Please see `GISAID <https://gisaid.org/publish/>`__ for more information.
 
 Column 19: ``submitting_lab``
 --------------------------------------
 
-Please see `GISAID <https://www.gisaid.org/help/publish-with-gisaid-references/>`__ for more information.
+Please see `GISAID <https://gisaid.org/publish/>`__ for more information.
 
 Column 20: ``authors``
 --------------------------------------
@@ -127,7 +127,7 @@ Author of the genome sequence, or the paper which announced this genome. Typical
 Column 21: ``url``
 --------------------------------------
 
-The URL, if available, pointing to the genome data. For most SARS-CoV-2 data this is https://www.gisaid.org.
+The URL, if available, pointing to the genome data. For most SARS-CoV-2 data this is https://gisaid.org.
 
 Column 22: ``title``
 --------------------------------------

diff --git a/docs/src/reference/remote_inputs.rst b/docs/src/reference/remote_inputs.rst
@@ -27,7 +27,7 @@ Entire metadata & sequences data is uploaded from the ``ncov-ingest`` workflows
 -  ``metadata.tsv.zst`` and ``metadata.tsv.gz``
 -  ``sequences.fasta.zst`` and ``sequences.fasta.xz``
 -  ``nextclade.tsv.zst`` and ``nextclade.tsv.gz``
--  ``aligned.fasta.zst`` and ``aligned.fasta.xz`` (Alignment via `Nextclade <https://docs.nextstrain.org/projects/nextclade/en/stable/user/output-files.html#aligned-nucleotide-sequences>`__. The default reference genome is `MN908947 <https://www.ncbi.nlm.nih.gov/nuccore/MN908947>`__ (Wuhan-Hu-1))
+-  ``aligned.fasta.zst`` and ``aligned.fasta.xz`` (Alignment via `Nextclade <https://docs.nextstrain.org/projects/nextclade/en/stable/user/output-files/02-nuc-alignment.html>`__. The default reference genome is `MN908947 <https://www.ncbi.nlm.nih.gov/nuccore/MN908947>`__ (Wuhan-Hu-1))
 -  ``additional_info.tsv.zst`` and ``additional_info.tsv.gz`` (GISAID only)
 -  ``flagged_metadata.txt.zst`` and ``flagged_metadata.txt.gz`` (GISAID only)
 

diff --git a/docs/src/reference/workflow-config-file.rst b/docs/src/reference/workflow-config-file.rst
@@ -15,6 +15,8 @@ Primary configuration
 Parameters in this section define the main inputs and outputs of the workflow, as well as the commonly used ``subsampling`` rule.
 Often these will be the only parameters you need to modify.
 
+.. _inputs:
+
 inputs
 ------
 
@@ -198,7 +200,7 @@ subsampling
 -----------
 
 -  type: object
--  description: Schemes for subsampling data prior to phylogenetic inference to avoid sampling bias or focus an analysis on specific spatial and/or temporal scales. `See the SARS-CoV-2 tutorial for more details on defining subsampling schemes <../reference/customizing-analysis.html#subsampling>`__.
+-  description: Schemes for subsampling data prior to phylogenetic inference to avoid sampling bias or focus an analysis on specific spatial and/or temporal scales. See the :doc:`genomic surveillance tutorial <../tutorial/genomic-surveillance>` for an example.
 
 Predefined subsampling schemes are:
 
@@ -400,6 +402,7 @@ strip_strain_prefixes
 -  description: A list of prefixes to strip from strain names in metadata and sequence records to maintain consistent strain names when analyzing data from multiple sources.
 -  default: ``["hCoV-19/", "SARS-CoV-2/"]``
 
+.. _auspice_json_prefix:
 
 auspice_json_prefix
 -------------------
@@ -595,6 +598,8 @@ Per-Rule configuration
 Each top-level parameter here corresponds to a single Snakemake rule.
 Note that ``subsampling`` is a commonly used rule configuration which is described separately in the Primary configuration section.
 
+.. _sanitize_metadata:
+
 sanitize_metadata
 -----------------
 

diff --git a/docs/src/tutorial/custom-data.rst b/docs/src/tutorial/custom-data.rst
@@ -12,7 +12,7 @@ Prerequisites
 -------------
 
 1. :doc:`example-data`. This tutorial sets up the command line environment used in the following tutorial.
-2. `Register for a GISAID account <https://www.gisaid.org/registration/register/>`_, if you do not have one yet. However, registration may take a few days. Follow :doc:`alternative data preparation methods <../guides/data-prep/index>` in place of :ref:`custom-data-curate-data-from-gisaid`, if you wish to continue the following tutorial in the meantime.
+2. `Register for a GISAID account <https://gisaid.org/register//>`_, if you do not have one yet. However, registration may take a few days. Follow :doc:`alternative data preparation methods <../guides/data-prep/index>` in place of :ref:`custom-data-curate-data-from-gisaid`, if you wish to continue the following tutorial in the meantime.
 
 Setup
 -----
@@ -30,7 +30,7 @@ Curate data from GISAID
 
 We will retrieve 10 sequences from GISAID's EpiCoV database.
 
-1. Navigate to `GISAID <https://www.gisaid.org/>`__ and select **Login**.
+1. Navigate to `GISAID <https://gisaid.org/>`__ and select **Login**.
 
    .. image:: ../images/gisaid-homepage.png
       :width: 400

diff --git a/docs/src/tutorial/genomic-surveillance.rst b/docs/src/tutorial/genomic-surveillance.rst
@@ -15,7 +15,7 @@ Prerequisites
 -------------
 
 1. :doc:`custom-data`. This tutorial introduces concepts expanded by the following tutorial.
-2. `Register for a GISAID account <https://www.gisaid.org/registration/register/>`_, if you do not have one yet. However, registration may take a few days. Follow :doc:`alternative data preparation methods <../guides/data-prep/index>` in place of :ref:`genomic-surveillance-curate-data-from-gisaid`, if you wish to continue the following tutorial in the meantime.
+2. `Register for a GISAID account <https://gisaid.org/registration/>`_, if you do not have one yet. However, registration may take a few days. Follow :doc:`alternative data preparation methods <../guides/data-prep/index>` in place of :ref:`genomic-surveillance-curate-data-from-gisaid`, if you wish to continue the following tutorial in the meantime.
 
 Setup
 -----
@@ -33,7 +33,7 @@ Curate data from GISAID
 
 We will download a focal set of Idaho sequences from GISAID's EpiCoV database.
 
-1. Navigate to `GISAID <https://www.gisaid.org/>`__, **Login**, and go to **EpiCoV** > **Search**.
+1. Navigate to `GISAID <https://gisaid.org/>`__, **Login**, and go to **EpiCoV** > **Search**.
 
    .. image:: ../images/gisaid-epicov-search.png
       :width: 400

diff --git a/docs/src/tutorial/next-steps.rst b/docs/src/tutorial/next-steps.rst
@@ -73,7 +73,7 @@ Additional resources
 
    - `An applied genomic epidemiological handbook <https://alliblk.github.io/genepi-book/intro.html>`__ by Allison Black and Gytis Dudas
    - `Genomic Epidemiology Seminar Series <https://czgenepi.org/resources>`__ by Chan Zuckerberg Initiative Genomic Epidemiology (CZ GEN EPI)
-   - `COVID-19 Genomic Epidemiology Toolkit <https://www.cdc.gov/amd/training/covid-19-gen-epi-toolkit.html>`__ by Centers for Disease Control and Prevention (CDC)
+   - `COVID-19 Genomic Epidemiology Toolkit <https://www.cdc.gov/advanced-molecular-detection/php/training/?CDC_AAref_Val=https://www.cdc.gov/amd/training/covid-19-gen-epi-toolkit.html>`__ by Centers for Disease Control and Prevention (CDC)
 
 - :doc:`Review all possible options to configure your SARS-CoV-2 analyses with Nextstrain <../reference/workflow-config-file>`.
 - Watch `this 1-hour video overview <https://youtu.be/m4_F2tG58Pc>`__ by Heather Blankenship on how to deploy Nextstrain for a Public Health lab.
diff --git a/docs/src/tutorial/setup.rst b/docs/src/tutorial/setup.rst
@@ -10,7 +10,7 @@ Register for a GISAID account
 -----------------------------
 
 Some tutorials rely on data downloaded from `GISAID <https://gisaid.org/>`_.
-If you do not already have one, `register for a GISAID account <https://www.gisaid.org/registration/register/>`_ now.
+If you do not already have one, `register for a GISAID account <https://gisaid.org/registration/>`_ now.
 Registration may take a few days.
 
 Install Nextstrain components

diff --git a/docs/src/visualization/interpretation.rst b/docs/src/visualization/interpretation.rst
@@ -10,7 +10,7 @@ Introductory resources
 
 -  How to interact with Auspice (the engine for viewing trees): https://neherlab.org/201901_krisp_auspice.html
 
--  Overview of genomic epidemiology (older, but still relevant and clear): http://evolve.zoo.ox.ac.uk/Evolve/Oliver_Pybus_files/EvolAnalysisOfDynamicsOfViruses.pdf
+-  Overview of genomic epidemiology (older, but still relevant and clear): https://www.nature.com/articles/nrg2583
 
 Case Studies
 ------------

diff --git a/docs/src/visualization/narratives.rst b/docs/src/visualization/narratives.rst
@@ -5,7 +5,7 @@ Nextstrain Narratives allow you to pair a specific view of a dataset with text a
 
 For examples, `see our weekly Situation Reports <https://nextstrain.org/ncov-sit-reps>`__ from the first several months of the pandemic.
 
-You can `read more about narratives <https://nextstrain.org/docs/narratives/introduction>`__ or `watch our Nextstrain narratives tutorial videos <https://www.youtube.com/playlist?list=PLsFWZl6SQqWxN9SkbgdjU8sylIfhZNDiW>`_. We've also `provided a template narrative file <https://github.com/nextstrain/ncov/tree/master/narratives/ncov_template_narrative.md>`__ for you to edit.
+You can `read more about narratives <https://nextstrain.org/docs/narratives/introduction>`__ or `watch our Nextstrain narratives tutorial videos <https://www.youtube.com/playlist?list=PLsFWZl6SQqWxN9SkbgdjU8sylIfhZNDiW>`_. We've also `provided a template narrative file <https://github.com/nextstrain/ncov/blob/-/narratives/ncov_template_narrative.md>`__ for you to edit.
 
 You can preview the template narrative by navigating to https://nextstrain.org/community/narratives/nextstrain/ncov/template/narrative.