Merge pull request #1533 from nextstrain/docs-fixes

Docs fixes

docs/README.md

@@ -20,7 +20,7 @@ You can now build the documentation with:
 which invokes Sphinx to build static HTML pages in `build/html/`.
 You can view them by running:
 
-    open build/html/index.html
+    open _build/html/index.html
 
 You can clean the build directory for a fresh start with:
 

docs/customise-client/index.rst → docs/customise-client/overview.rst

@@ -1,5 +1,5 @@
 ======================================
-Customising the Auspice Client
+Overview (Client)
 ======================================
 
 
@@ -29,12 +29,3 @@ AGPL Source Code Requirement
 Auspice is distributed under `AGPL 3.0 <https://www.gnu.org/licenses/agpl-3.0.en.html>`_.
 Any modifications made to the auspice source code, including build-time customisations as described here, must be made publicly available. 
 We ask that the "Powered by Nextstrain" text and link, rendered below the data visualisations, be maintained in all customised versions of auspice, in keeping with the spirit of scientific citations.
-
-
-.. toctree::
-   :maxdepth: 0
-   :titlesonly:
-   :caption: Pages available
-
-   api
-   requests

docs/index.rst

@@ -46,15 +46,61 @@ Source code to Nextstrain is made available under the terms of the `GNU Affero G
 
 
 .. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :caption: Introduction
+   :hidden:
+
+   introduction/install
+   introduction/how-to-run
+
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :caption: Functionality
+   :hidden:
+
+   advanced-functionality/second-trees
+   advanced-functionality/view-settings
+   advanced-functionality/drag-drop-csv-tsv
+   advanced-functionality/misc
+
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :caption: Customising Auspice
+   :hidden:
+
+   customise-client/overview
+   customise-client/api
+   customise-client/requests
+
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :caption: Auspice servers
    :hidden:
-   :maxdepth: 2
-   :caption: Table of contents
-   :name: mastertoc
+
+   server/overview
+   server/api
+   server/authentication
+
+
+.. toctree::
+   :maxdepth: 1
    :titlesonly:
+   :caption: Releases
+   :hidden:
 
-   self
-   introduction/index
-   advanced-functionality/index
-   customise-client/index
-   server/index
    releases/index
+
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :hidden:
+
+   Stuck? Ask us on the discussion board. We're happy to help! <https://discussion.nextstrain.org/>

docs/server/index.rst → docs/server/overview.rst

@@ -1,12 +1,12 @@
 ======================================
-Auspice servers
+Overview (Server)
 ======================================
 
 The Auspice client (i.e. what you see in the web browser) requires a server behind it to
 - (a) serve the client HTML, CSS & JavaScript to the browser and
 - (b) handle certain `GET <https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods>`_ requests from the client, for instance "give me the zika dataset to display".
 
-We provide a basic server to run Auspice locally -- any time you run `auspice view` or `auspice develop` you're running a server!
+We provide a basic server to run Auspice locally -- any time you run ``auspice view`` or ``auspice develop`` you're running a server!
 In these cases, the server is running on your computer, sending datasets and narratives, which are stored on your machine, to the Auspice client.
 Alternatively, you can build your own server -- it just needs to satisfy the above two requirements.
 
@@ -20,11 +20,11 @@ Currently the client is able to make three requests:
    :header: "address", "description"
    :widths: 1, 2
 
-   `/charon/getAvailable`, return a list of available datasets and narratives
-   `/charon/getDataset`, return the requested dataset
-   `/charon/getNarrative`, return the requested narrative
+   ``/charon/getAvailable``, return a list of available datasets and narratives
+   ``/charon/getDataset``, return the requested dataset
+   ``/charon/getNarrative``, return the requested narrative
 
-For instance, when you're running `auspice view` if you go to `localhost:4000/charon/getAvailable <http://localhost:4000/charon/getAvailable>`_ you'll see a list of the available datasets and narratives known to the server.
+For instance, when you're running ``auspice view`` if you go to `localhost:4000/charon/getAvailable <http://localhost:4000/charon/getAvailable>`_ you'll see a list of the available datasets and narratives known to the server.
 Similarly, nextstrain.org is a server which has handlers for these three API endpoints, so if you visit `nextstrain.org/charon/getAvailable <https://nextstrain.org/charon/getAvailable>`_ you'll see Nextstrain's available datasets.
 
 See `the server API <../server/api.html>`_ for details about each of these requests.
@@ -59,27 +59,20 @@ Writing Your Own Custom Server
 
 The provided Auspice server also lets you define your own handlers, allowing plenty of flexibility in how requests are handled.
 But if you _really_ want to implement your own server, then you only need to implement two things:
-- serve the `index.html` file (and linked javascript bundles) which are created by `auspice build` _and_
+- serve the `index.html` file (and linked javascript bundles) which are created by ``auspice build`` _and_
 - handle the three GET requests detailed above
 
-(If you're interested, this is what we do with `nextstrain.org <https://nextstrain.org>`_, where only some of the pages use Auspice. You can see all the code behind that server [here](https://github.com/nextstrain/nextstrain.org).)
+.. note::
+   If you're interested, this is what we do with `nextstrain.org <https://nextstrain.org>`_, where only some of the pages use Auspice (`code <https://github.com/nextstrain/nextstrain.org>`_).
 
 
 Deploying via Heroku
 ======================================
 
 It should be simple to deploy a custom version of auspice to any server, but we have experience using `Heroku <https://heroku.com/>`_ apps for this.
 Deploying to Heroku is straightforward, but there are a few points to note:
-1. You must set the config var `HOST` to `0.0.0.0` for the app.
-1. You will need to either create a `Procfile` or a `npm run start` script which calls `auspice view` (or `npx auspice view` depending on how you implement auspice)
-1. Make sure the datasets to be served are either (a) included in your git repo or (b) downloaded by the heroku build pipeline.
-`We use option (b) <https://github.com/nextstrain/auspice/blob/master/package.json>`_ by specifing a npm script called `heroku-postbuild`.
-
 
-.. toctree::
-   :maxdepth: 0
-   :titlesonly:
-   :caption: Pages available
+1. You must set the config var ``HOST=0.0.0.0`` for the app.
+2. You will need to either create a ``Procfile`` or a ``npm run start`` script which calls ``auspice view`` (or ``npx auspice view`` depending on how you implement auspice).
+3. Make sure the datasets to be served are either (a) included in your git repo or (b) downloaded by the heroku build pipeline. `We use option (b) <https://github.com/nextstrain/auspice/blob/master/package.json>`_ by specifying a npm script called ``heroku-postbuild``.
 
-   api
-   authentication