Browse Source

[docs] minor fixes and content improvements

In preparation for release
master
james hadfield 1 year ago
parent
commit
a8cdc08e17
  1. 3
      docs/advanced-functionality/index.rst
  2. 10
      docs/customise-client/api.md
  3. 26
      docs/customise-client/index.rst
  4. 23
      docs/customise-client/introduction.md
  5. 3
      docs/introduction/index.rst
  6. 3
      docs/releases/index.rst
  7. 71
      docs/server/index.rst

3
docs/advanced-functionality/index.rst

@ -2,10 +2,9 @@
Advanced Functionality
======================================
This page shouldn't be rendered & should jump to the first TOC entry instead. TODO.
See below for the pages explaining more advanced usage of Auspice:
.. toctree::
:hidden:
:maxdepth: 0
:titlesonly:

10
docs/customise-client/api.md

@ -29,7 +29,7 @@ A useful reference may be the [customisation JSON file](https://github.com/nexts
---
## Sidebar Theme
### Sidebar Theme
The appearence of the sidebar can be customised by specifing a theme in the config JSON used to build Auspice.
This theme is then available (via [styled-components](https://www.styled-components.com/)) to the components rendered in the sidebar.
@ -61,7 +61,7 @@ For instance, here is the customisation used by nextstrain.org:
# Components
## Components
One way to extend Auspice is by replacing React components with your own custom components.
These custom components will receive props defined here, which can be used to update the rendering of the component using the normal react lifecycle methods.
@ -70,7 +70,7 @@ Right now this is only available for the splash page and nav-bar components, who
Each component must be the default export of a javascript file which is specified in the (client) config JSON passed to Auspice at build time (`auspice build` or `auspice develop`).
## Nav-bar Component
### Nav-bar Component
**Build config:**
```json
@ -92,7 +92,7 @@ Where the javascript file contains a default export of a React component.
## Splash component
### Splash component
Define a custom splash page for Auspice. Please note that this is extremely expirimental and the interface is expected to change.
@ -117,7 +117,7 @@ Where the javascript file contains a default export of a React component.
---
## Specifying the API server address
### 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".

26
docs/customise-client/index.rst

@ -2,13 +2,33 @@
Customising the Auspice Client
======================================
This page shouldn't be rendered & should jump to the first TOC entry instead. TODO.
Auspice allows you to customise the appearance and functionality of Auspice `when the client is built <../introduction/how-to-run.html#auspice-build>`_.
This is how Auspice running locally and nextstrain.org look different, despite both using "Auspice".
.. image:: ../assets/auspice-vs-nextstrain.png
*Notice the difference? Default Auspice (left) and nextstrain.org's customised version (right)*
This is achieved by providing a JSON at build time to Auspice which defines the desired customisations via:
.. code-block:: bash
auspice build --extend <JSON>
`Here's <https://github.com/nextstrain/nextstrain.org/blob/master/auspice-client/customisations/config.json>`_ the file used by nextstrain.org to change the appearance of Auspice in the above image.
See the `client customisation API <api.html>`_ for the available options.
.. toctree::
:hidden:
:maxdepth: 0
:titlesonly:
:caption: Pages available
introduction
api
requests

23
docs/customise-client/introduction.md

@ -1,23 +0,0 @@
# Customising the Auspice Client
Auspice allows you to customise the appearance and functionality of Auspice [when the client is built](introduction/how-to-run.md#auspice-build).
This is how Auspice running locally and nextstrain.org look different, despite both using "Auspice".
![mumps](../assets/auspice-vs-nextstrain.png)
*Notice the difference? Default Auspice (left) and nextstrain.org's customised version (right)*
This is achieved by providing a JSON at build time to Auspice which defines the desired customisations via:
```bash
auspice build --extend <JSON>
```
[Here's](https://github.com/nextstrain/nextstrain.org/blob/master/auspice-client/customisations/config.json) the file used by nextstrain.org to change the appearance of Auspice in the above image.
See the [client customisation API](api.md) for the available options.

3
docs/introduction/index.rst

@ -2,10 +2,9 @@
Introduction
======================================
This page shouldn't be rendered & should jump to the first TOC entry instead. TODO.
See below for the pages explaining the basics of Auspice:
.. toctree::
:hidden:
:maxdepth: 0
:titlesonly:

3
docs/releases/index.rst

@ -2,10 +2,7 @@
Releases
======================================
This page shouldn't be rendered & should jump to the first TOC entry instead. TODO.
.. toctree::
:hidden:
:maxdepth: 0
:titlesonly:

71
docs/server/index.rst

@ -2,13 +2,78 @@
Auspice servers
======================================
This page shouldn't be rendered & should jump to the first TOC entry instead. TODO.
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!
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.
GET Requests
======================================
Currently the client is able to make three requests:
.. csv-table::
: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
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.
.. note::
Note that "/charon" can be changed to any address you wish by customising the client at build time.
See `the client-cusomisation API <../customise-client/api.html>` for more details.
The "Default" Auspice Server
======================================
The server provided with Auspice is intended to be run on your local setup.
It thus scans the directories you provide when you run it in order to find datasets and narratives to serve.
It has "handlers" for each of the above 3 requests -- i.e. bits of code that tell it how to handle each request.
Customising the Default Auspice Server
======================================
You can customise the default Auspice server by supplying your own handlers for each of the three GET requests.
See `the API documentation <../server/api.html#suppling-custom-handlers-to-the-auspice-server>`_ for how to define these and provide them to `auspice view`.
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_
- 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).)
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::
:hidden:
:maxdepth: 0
:titlesonly:
:caption: Pages available
introduction
api
authentication
Loading…
Cancel
Save