Fix links and overall rST formatting

docs/advanced-functionality/drag-drop-csv-tsv.rst

@@ -87,7 +87,11 @@ The following fields are ignored completely. (Some of these may be allowed in th
    month
    day
 
-Fields which end with certain strings are treated as follows: - ``__autocolour``: this suffix is dropped, but the column is otherwise parsed as normal - ``__colour``: see above section on adding colours - ``__shape``: this column is currently ignored
+Fields which end with certain strings are treated as follows:
+
+- ``__autocolour``: this suffix is dropped, but the column is otherwise parsed as normal
+- ``__colour``: see above section on adding colours
+- ``__shape``: this column is currently ignored
 
 The following columns are interpreted as geographic locations (see section above) and therefore are not added as a colouring:
 

docs/advanced-functionality/misc.rst

@@ -15,12 +15,22 @@ If a trait is not set on a node it is considered missing, as well as if (after c
 GISAID specific changes to behavior
 -----------------------------------
 
-**GISAID data provenance annotation**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+GISAID data provenance annotation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If the dataset JSON defines a data provenance named ``"GISAID"`` (``JSON → metadata → data_provenance``, see `schema <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v2.json>`__), then there are two changes to Auspice behaviour: 1. The GISAID data provenance text (displayed at the top of the page in auspice) will be replaced with the GISAID logo, which is also a link to `gisaid.org <https://gisaid.org>`__. 2. The available metadata for download is different. We now use a “Per-sample acknowledgments table” where each row is a strain in the tree, with the following columns: - ``strain`` - ``gisaid_epi_isl`` - ``genbank_accession`` - ``originating_lab`` - ``submitting_lab`` - ``author``
+If the dataset JSON defines a data provenance named ``"GISAID"`` (``JSON → metadata → data_provenance``, see `schema <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v2.json>`__), then there are two changes to Auspice behaviour:
 
-**Node annotated with ``gisaid_epi_isl``**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+1. The GISAID data provenance text (displayed at the top of the page in auspice) will be replaced with the GISAID logo, which is also a link to `gisaid.org <https://gisaid.org>`__.
+2. The available metadata for download is different. We now use a “Per-sample acknowledgments table” where each row is a strain in the tree, with the following columns:
+
+   - ``strain``
+   - ``gisaid_epi_isl``
+   - ``genbank_accession``
+   - ``originating_lab``
+   - ``submitting_lab``
+   - ``author``
+
+Node annotated with ``gisaid_epi_isl``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When hovering or clicking on tips (in the tree), nodes annotated with ``gisaid_epi_isl`` will behave slightly differently. These info-boxes will display “GISAID EPI ISL” and, in the tip-clicked info-panel, the value will also be a link to `gisaid.org <https://gisaid.org>`__.

docs/advanced-functionality/second-trees.rst

@@ -13,6 +13,10 @@ You can compare any two datasets which you have available -- for instance if you
 Showing potential datasets in the sidebar
 -----------------------------------------
 
-Depending on the way you've labelled your datasets, potential second trees are available in a sidebar dropdown. These are defined by the `getAvailable API request <server/api.md#charon-getavailable>`__. Currently, the logic in ``auspice view`` is to match all datasets which: - contain the same first "part" of the URL -- interpreted here to represent the same pathogen. - have the same number of "parts" in the URL (parts are delimited by a ``_`` in the filename or a ``/`` in the URL). - differ from the currently selected dataset by only 1 part.
+Depending on the way you've labelled your datasets, potential second trees are available in a sidebar dropdown. These are defined by the :ref:`getAvailable API request <server-api-charon-getavailable>`. Currently, the logic in ``auspice view`` is to match all datasets which:
+
+- contain the same first "part" of the URL -- interpreted here to represent the same pathogen.
+- have the same number of "parts" in the URL (parts are delimited by a ``_`` in the filename or a ``/`` in the URL).
+- differ from the currently selected dataset by only 1 part.
 
 .. |two-trees| image:: ../assets/tangle.png

docs/advanced-functionality/view-settings.rst

@@ -1,7 +1,11 @@
 View Settings
 =============
 
-View settings refer to things such as how we display the tree (radial? root-to-tip?), what panels we display (map? tree? both?), what colouring we are using etcetera. There are three ways these can be controlled: 1. The defaults are configured by the dataset creators (and stored as "display defaults" in the dataset JSON). This allows 2. Interacting with the visualisation (e.g. changing the color-by) modifies the view, and the URL is changed accordingly. For instance, change `nextstrain.org/zika <https://nextstrain.org/zika>`__ to have a color-by of author, and you'll see the URL silently update to `?c=author <https://nextstrain.org/zika?c=author>`__. If you reload the page or share this URL, then the color-by is set via this URL. 3. Narratives, in which the narrative author chooses different "views" for each page, are created by associating each page with a URL (see (2)) which defines a specific view into the data.
+View settings refer to things such as how we display the tree (radial? root-to-tip?), what panels we display (map? tree? both?), what colouring we are using etcetera. There are three ways these can be controlled:
+
+1. The defaults are configured by the dataset creators (and stored as "display defaults" in the dataset JSON). This allows
+2. Interacting with the visualisation (e.g. changing the color-by) modifies the view, and the URL is changed accordingly. For instance, change `nextstrain.org/zika <https://nextstrain.org/zika>`__ to have a color-by of author, and you'll see the URL silently update to `?c=author <https://nextstrain.org/zika?c=author>`__. If you reload the page or share this URL, then the color-by is set via this URL.
+3. Narratives, in which the narrative author chooses different "views" for each page, are created by associating each page with a URL (see (2)) which defines a specific view into the data.
 
 Auspice (hardcoded) defaults
 ----------------------------

docs/customise-client/api.rst

@@ -1,6 +1,8 @@
 Client Customisation API
 ========================
 
+.. warning::
+
    The functionality detailed in this page needs more attention, both in terms of testing and code development. We expect there to be some bugs and possible API changes. If you rely on this functionality, we recommend you pin your installation of Auspice to a specific version. Please `get in touch with us <mailto:[email protected]>`__ if you are using these customisations so that we can work with you!
 
 This page details the available options and format of the customisations available at (client) build time. They are contained in a JSON file supplied to Auspice via
@@ -9,7 +11,11 @@ This page details the available options and format of the customisations availab
 
    auspice build --extend <JSON>
 
-*Note that the hot-reloading development functionality does not work for code which is included via this client customisation mechanism.* *Thus, while you can run ``auspice develop --extend <JSON>`` it will not update as you may expect!*
+.. note::
+
+   The hot-reloading development functionality does not work for code which is included via this client customisation mechanism. Thus, while you can run ``auspice develop --extend <JSON>`` it will not update as you may expect!
+
+.. _client-api-available-customisations:
 
 Available Customisations
 ------------------------
@@ -26,9 +32,9 @@ The following are definable as top-level keys of the JSON file. A useful referen
 -  ``serverAddress`` Specify the address / prefix which the auspice client uses for API requests.
 -  ``mapTiles`` Specify the address (and other information) for the tiles used to render the map.
 
-..
+.. note::
 
-   Please remember to make any modifications, including customisations described here, publicly available. See `the previous page <./index.rst>`__ for more details.
+   Please remember to make any modifications, including customisations described here, publicly available. See :doc:`the previous page <overview>` for more details.
 
 --------------
 
@@ -138,9 +144,11 @@ Where the javascript file contains a default export of a React component.
 Specifying the API server address
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-By default, the client makes API requests (`as detailed here <requests.md>`__) to "/charon/getAvailable", "/charon/getDataset" etc. This is using the default server address of "/charon". This can be changed by specifying ``serverAddress`` in the customisation JSON.
+By default, the client makes API requests (:doc:`as detailed here <requests>`) to "/charon/getAvailable", "/charon/getDataset" etc. This is using the default server address of "/charon". This can be changed by specifying ``serverAddress`` in the customisation JSON.
+
+.. note::
 
-   Note that if you specify a ``serverAddress`` on a different origin (protocol + domain + port) than Auspice, the server will need to send CORS headers to permit the requests from Auspice.
+   If you specify a ``serverAddress`` on a different origin (protocol + domain + port) than Auspice, the server will need to send CORS headers to permit the requests from Auspice.
 
 --------------
 

docs/customise-client/requests.rst

@@ -26,7 +26,7 @@ When a dataset, narrative, or listing of available datasets is to be displayed i
 -  ``/charon/getDataset`` -- return the requested dataset
 -  ``/charon/getNarrative`` -- return the requested narrative
 
-See `the server API documentation <../server/api.md>`__ for more details about the requests, or the `client customisation API <api.md>`__ for the ability to change "/charon" to a different value.
+See :doc:`the server API documentation <../server/api>` for more details about the requests, or the :doc:`client customisation API <api>` for the ability to change "/charon" to a different value.
 
 Image Requests
 ~~~~~~~~~~~~~~
@@ -51,4 +51,4 @@ If a map is displayed by Auspice the individual tiles are requested from api.map
 Google Analytics (Optional)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Auspice has the potential to include Google Analytics in a limited fashion. See `the client customisation API documentation <customise-client/api.md#available-customisations>`__ for how to set this. Note that these requests are only made if you specify a Google Analytics key during build-time customisation of the client.
+Auspice has the potential to include Google Analytics in a limited fashion. See :ref:`the client customisation API documentation <client-api-available-customisations>` for how to set this. Note that these requests are only made if you specify a Google Analytics key during build-time customisation of the client.

docs/introduction/how-to-run.rst

@@ -41,12 +41,16 @@ This is the main command we'll run Auspice with, as it makes Auspice available i
 | narrativeDir        | PATH                     | Directory where narratives (Markdown files) are sourced. This is ignored if you define custom handlers. |
 +---------------------+--------------------------+---------------------------------------------------------------------------------------------------------+
 
-For more complicated setups, where you define your own server handlers, see `supplying custom handlers to the Auspice server <../server/api.md#supplying-custom-handlers-to-the-auspice-server>`__.
+For more complicated setups, where you define your own server handlers, see :ref:`supplying custom handlers to the Auspice server <server-api-supplying-custom-handlers>`.
 
 ``auspice build``
 -----------------
 
-Build the client source code bundle. This is needed in three cases: 1. You have installed Auspice from source, or updated the source code. 1. You are editing the source code and need to rebuild the client 1. You wish to build a customised version of the Auspice client. See `Customising Auspice <../customise-client/index>`__ for more info.
+Build the client source code bundle. This is needed in three cases:
+
+1. You have installed Auspice from source, or updated the source code.
+2. You are editing the source code and need to rebuild the client
+3. You wish to build a customised version of the Auspice client. See `Customising Auspice <../customise-client/index>`__ for more info.
 
 ``auspice develop``
 -------------------
@@ -58,7 +62,7 @@ This is only useful if you are editing the client source code!
 ``auspice convert``
 -------------------
 
-This is a utility command to convert between dataset formats. Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is `programatically importable <../server/api.md#convertfromv1>`__.
+This is a utility command to convert between dataset formats. Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is :ref:`programatically importable <server-api-convertfromv1>`.
 
 Right now, ``auspice view`` will automatically convert "v1" JSONs into "v2" JSONs, so there's no need to do this yourself.
 
@@ -67,29 +71,49 @@ Input File Formats
 
 Auspice is agnostic about the data it visualises -- they don't have to be viral genomes, or real-time, or generated in Augur. (They do, however have to be in a specific file format.)
 
-Auspice takes two different file types: \* Datasets (the tree, map, etc.), which are defined as one or more JSON files. \* Narratives, which are specified as a Markdown file.
+Auspice takes two different file types:
+
+* Datasets (the tree, map, etc.), which are defined as one or more JSON files.
+* Narratives, which are specified as a Markdown file.
 
-See the `Server API <../server/api.md>`__ for more details about the file formats an Auspice server (e.g. ``auspice view``) sends to the client.
+See the :doc:`Server API <../server/api>` for more details about the file formats an Auspice server (e.g. ``auspice view``) sends to the client.
 
 Dataset JSONs
 ~~~~~~~~~~~~~
 
 Currently we mainly use `Augur <https://github.com/nextstrain/augur>`__ to create these datasets. See `the Nextstrain documentation <https://nextstrain.org/docs/bioinformatics/introduction-to-augur>`__ for more details on this process.
 
-Datasets JSONs include: \* Auspice v2 JSON (required) - `schema here <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v2.json>`__. It includes the following information: \* ``tree``: The tree structure encoded as a deeply nested JSON object. \* Traits (such as country, divergence, collection date, attributions, etc.) are stored on each node. \* The presence of a ``children`` property indicates that it's an internal node and contains the child objects. \* ``metadata``: Additional data to control and inform the visualization. \* Frequency JSON (optional) - `example here <http://data.nextstrain.org/flu_seasonal_h3n2_ha_2y_tip-frequencies.json>`__ \* Generates the frequencies panel, e.g. on `nextstrain.org/flu <https://nextstrain.org/flu>`__.
+Datasets JSONs include:
+
+* Auspice v2 JSON (required) - `schema here <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v2.json>`__. It includes the following information:
+   * ``tree``: The tree structure encoded as a deeply nested JSON object.
+      * Traits (such as country, divergence, collection date, attributions, etc.) are stored on each node.
+      * The presence of a ``children`` property indicates that it's an internal node and contains the child objects.
+   * ``metadata``: Additional data to control and inform the visualization.
+* Frequency JSON (optional) - `example here <http://data.nextstrain.org/flu_seasonal_h3n2_ha_2y_tip-frequencies.json>`__
+   * Generates the frequencies panel, e.g. on `nextstrain.org/flu <https://nextstrain.org/flu>`__.
+
+.. note::
 
    We are working on ways to make datasets in Newick / Nexus formats available. You can see an early prototype of this at `auspice-us.herokuapp.com <https://auspice-us.herokuapp.com/>`__ where you can drop on Newick (and CSV) files. Using BEAST trees is possible, but you have to use Augur to convert them first.
 
-..
+.. note::
 
-   If you happen to maintain builds that rely on Auspice v1, don’t worry - Auspice v2 is backward compatible and accepts the v1 format as well. The v1 schema is also available below. See `the v2 release notes <../releases/v2.md>`__ for details and motivation for the v2 format.
+   If you happen to maintain builds that rely on Auspice v1, don't worry - Auspice v2 is backward compatible and accepts the v1 format as well. The v1 schema is also available below. See :doc:`the v2 release notes <../releases/v2>` for details and motivation for the v2 format.
 
 Auspice v1 JSONs (for backwards compatibility use only)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Auspice works with the v1 format for backwards compatibility. *The zika dataset we download above is in this format.*
 
-This format includes: \* Tree JSON (required) - `schema here <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v1-tree.json>`__ \* The same tree information as in the v2 JSON above in a separate file whose name *must* end with ``_tree.json``. \* Metadata JSON (required) - `schema here <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v1-meta.json>`__ \* The same metadata information as in the v2 JSON above in a separate file whose name *must* end with ``_meta.json`` and have the same prefix as the tree JSON above. \* Frequency JSON (optional) - `example here <http://data.nextstrain.org/flu_seasonal_h3n2_ha_2y_tip-frequencies.json>`__ \* Generates the frequencies panel, e.g. on `nextstrain.org/flu <https://nextstrain.org/flu>`__.
+This format includes:
+
+* Tree JSON (required) - `schema here <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v1-tree.json>`__
+   * The same tree information as in the v2 JSON above in a separate file whose name *must* end with ``_tree.json``.
+* Metadata JSON (required) - `schema here <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v1-meta.json>`__
+   * The same metadata information as in the v2 JSON above in a separate file whose name *must* end with ``_meta.json`` and have the same prefix as the tree JSON above.
+* Frequency JSON (optional) - `example here <http://data.nextstrain.org/flu_seasonal_h3n2_ha_2y_tip-frequencies.json>`__
+   * Generates the frequencies panel, e.g. on `nextstrain.org/flu <https://nextstrain.org/flu>`__.
 
 Narratives
 ~~~~~~~~~~

docs/introduction/install.rst

@@ -27,7 +27,7 @@ Install Auspice as a user
 
    npm install --global auspice
 
-If you look at the `release notes <https://docs.nextstrain.org/projects/auspice/en/stable/releases/changelog.html>`__ you can see the changes that have been made to Auspice (see your version of Auspice via ``auspice --version``). To upgrade, you can run
+If you look at the :doc:`release notes <../releases/changelog>` you can see the changes that have been made to Auspice (see your version of Auspice via ``auspice --version``). To upgrade, you can run
 
 .. code:: bash