Commit 5dfc30d2 authored by james hadfield's avatar james hadfield
Browse files

draft v2 docs

Implement much improved splash page and create framework for docs pages (including new tutorial section). Individual doc pages are mostly incomplete.
parent 4a12316d
......@@ -21,6 +21,7 @@ All commands run from this directory (`docs-src`).
#### Installing dependencies
```bash
npm install
# you must also have installed the dependencies from the parent directory (`auspice`)
```
#### Developing (live reloading etc):
......
<?xml version="1.0" encoding="UTF-8"?>
<svg width="919px" height="501px" viewBox="0 0 919 501" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<!-- Generator: Sketch 53 (72520) - https://sketchapp.com -->
<title>Artboard</title>
<desc>Created with Sketch.</desc>
<g id="Artboard" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
<rect id="Rectangle" stroke="#30353F" fill="#D8D8D8" x="33.5" y="138.5" width="191" height="321" rx="5"></rect>
<rect id="Rectangle" stroke="#30353F" fill="#D8D8D8" x="360.5" y="39.5" width="191" height="420" rx="5"></rect>
<rect id="Rectangle" stroke="#30353F" fill="#D8D8D8" x="682.5" y="39.5" width="191" height="420" rx="5"></rect>
<text id="AUSPICE-(CLIENT)" font-family="Helvetica-Bold, Helvetica" font-size="17" font-weight="bold" fill="#30353F">
<tspan x="53" y="163">AUSPICE (CLIENT)</tspan>
</text>
<text id="serve-different-page" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="566.015" y="129">serve different </tspan>
<tspan x="564.461" y="146">page / redirect </tspan>
<tspan x="581.45" y="163">response</tspan>
</text>
<text id="API-request" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="252.058" y="169">API request</tspan>
</text>
<text id="cookie" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="596.878" y="238">cookie</tspan>
</text>
<text id="cookie-+-res-for-ori" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="241.654" y="253">cookie + res for </tspan>
<tspan x="255.234" y="270">original req</tspan>
</text>
<text id="No-cookie-set-/-not" font-family="Helvetica-Light, Helvetica" font-size="17" font-weight="300">
<tspan x="399.305" y="112" fill="#30353F">No cookie set / </tspan>
<tspan x="397.5795" y="132" fill="#30353F">not appropriate </tspan>
<tspan x="414.112" y="152" fill="#30353F">credentials</tspan>
<tspan x="456" y="172" font-family="Helvetica-Bold, Helvetica" font-weight="bold" fill="#5DA8A3"></tspan>
<tspan x="456" y="192" font-family="Helvetica-Bold, Helvetica" font-weight="bold" fill="#5DA8A3"></tspan>
</text>
<text id="Authenticated-:)" font-family="Helvetica-Light, Helvetica" font-size="17" font-weight="300">
<tspan x="396.0225" y="400" fill="#30353F">Authenticated :)</tspan>
<tspan x="516.9775" y="400" font-family="Helvetica-Bold, Helvetica" font-weight="bold" fill="#5DA8A3"></tspan>
<tspan x="456.5" y="420" font-family="Helvetica-Bold, Helvetica" font-weight="bold" fill="#5DA8A3"></tspan>
</text>
<text id="SERVER" font-family="Helvetica-Bold, Helvetica" font-size="17" font-weight="bold" fill="#30353F">
<tspan x="421.694824" y="66">SERVER</tspan>
</text>
<text id="CUSTOM-LOGIN-PAGE" font-family="Helvetica-Bold, Helvetica" font-size="17" font-weight="bold" fill="#30353F">
<tspan x="686.718262" y="67">CUSTOM LOGIN PAGE</tspan>
</text>
<path id="Line" d="M332.5,175.5 L234.5,175.5 L233.5,175.5 L233.5,173.5 L234.5,173.5 L332.5,173.5 L332.5,167.5 L346.5,174.5 L332.5,181.5 L332.5,175.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<text id="index.html-request" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="253.216" y="63">index.html </tspan>
<tspan x="261.896" y="80">request</tspan>
</text>
<path id="Line" d="M332.5,87.5 L234.5,87.5 L233.5,87.5 L233.5,85.5 L234.5,85.5 L332.5,85.5 L332.5,79.5 L346.5,86.5 L332.5,93.5 L332.5,87.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<text id="cookie-+-API-req" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="238.154" y="373">cookie + API req</tspan>
</text>
<path id="Line" d="M337.5,382.5 L239.5,382.5 L238.5,382.5 L238.5,380.5 L239.5,380.5 L337.5,380.5 L337.5,374.5 L351.5,381.5 L337.5,388.5 L337.5,382.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<path id="Line" d="M659.5,175.5 L561.5,175.5 L560.5,175.5 L560.5,173.5 L561.5,173.5 L659.5,173.5 L659.5,167.5 L673.5,174.5 L659.5,181.5 L659.5,175.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<path id="Line" d="M575.5,243.5 L673.5,243.5 L674.5,243.5 L674.5,245.5 L673.5,245.5 L575.5,245.5 L575.5,251.5 L561.5,244.5 L575.5,237.5 L575.5,243.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<path id="Line" d="M248.5,276.5 L346.5,276.5 L347.5,276.5 L347.5,278.5 L346.5,278.5 L248.5,278.5 L248.5,284.5 L234.5,277.5 L248.5,270.5 L248.5,276.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<text id="API-response" font-family="Helvetica-LightOblique, Helvetica" font-size="14" font-style="italic" font-weight="300" fill="#30353F">
<tspan x="253.612" y="415">API response</tspan>
</text>
<path id="Line" d="M251.5,419.5 L349.5,419.5 L350.5,419.5 L350.5,421.5 L349.5,421.5 L251.5,421.5 L251.5,427.5 L237.5,420.5 L251.5,413.5 L251.5,419.5 Z" fill="#30353F" fill-rule="nonzero"></path>
<text id="custom-authenticatio" font-family="Helvetica-Light, Helvetica" font-size="17" font-weight="300" fill="#30353F">
<tspan x="694.8685" y="192">custom authentication </tspan>
<tspan x="700.5635" y="212">implementation (e.g. </tspan>
<tspan x="730.3135" y="232">using Auth0)</tspan>
</text>
</g>
</svg>
\ No newline at end of file
---
title: Community Builds
---
> Needs to be expanded and updated with whatever we actually end up implementing!
Our desire is to develop a community of scientists using auspice, and easily sharing datasets is a crucial element of this!
To achieve this, we currently provide a way to access datasets committed to public GitHub repositories.
## How to use
#### What you'll need:
1. A public github repository -- e.g. `github.com/orgname/reponame`
2. A auspice (v2) JSON file -- [see here for details](introduction/data-formats.md)
#### Steps:
1. Create a folder called `auspice` in the repo
2. Add the (default) JSON file to this directory, with the same name as the repo.
3. (optional) you can add additional JSONs, they must start with the repo name and then contain additional fields seprated by a **_** character. E.g. `reponame_a_b.json`.
4. Commit the files to the master branch and push to GitHub.
5. That's it 💪
#### How to access:
1. "https://auspice.us/orgname/reponame" will access the default dataset
2. Additional JSONs can be found at "https://auspice.us/orgname/reponame/a/b"
> If you'd like a link to your dataset to be on the auspice.us front page then [give us an email 🤩](mailto:hello@nextstrain.org)
## Real World Example: Zika virus in the US Virgin Islands
[Alli Black's](https://bedford.io/team/allison-black/) analysis of Zika virus in the US Virgin Islands is being updated [in this github repo](https://github.com/blab/zika-usvi/) and you can see the most up-to-date results at [auspice.us/github/blab/zika-usvi](https://auspice.us/github/blab/zika-usvi)
## Incomplete list of community builds
* 😳
---
title: auspice.us
---
> Need a more snappy description of the website and maybe some screenshots.
Auspice.us is a [custom build of auspice](build-server/introduction.md) which allows users to simply drag & drop datasets onto the browser.
It also serves datasets from a GitHub, i.e. datasets which you have committed to a public github repository can be automatically visualised through auspice.us -- see [community-builds]("auspice.us/community-builds.md) for instructions.
---
title: API
---
> Should detail both the API endpoints, what's expected in the response.
Aso detail the exposed functions from `auspice` -- e.g. what you can get from `const { x, y } = require("auspice");`
# Current API description
Currently the client makes three requests:
* `/charon/getAvailable` -- return a list of available datasets and narratives
* `/charon/getDataset` -- return the requested dataset
* `/charon/getNarrative` -- return the requested narrative
You can choose to handle these in your own server, or provide handlers to the auspice (dev-)server which are called whenever these requests are received (see above).
## get available datasets: `/charon/getAvailable`
Query arguments:
* `prefix` (optional) - the pathname of the requesting page in auspice.
Response shape:
```json
{
"datasets": [
{"request": "URL of a dataset. Will become the prefix in a getDataset request"},
...
],
"narratives": [
{"request": "URL of a narrative. Will become the prefix in a getNarrative request"},
...
]
}
```
## get a dataset: `/charon/getDataset`
Query arguments:
* `prefix` (required) - the pathname of the requesting page in auspice. Use this to determine which dataset to return.
* `type` (optional) -- if specified, then the request is for an additional file (e.g. "tip-frequencies"), not the main dataset.
Response shape:
Auspice v2.0 JSON -- see [data formats](introduction/data-formats.md)
## get a narrative: `/charon/getNarrative`
> to do
---
title: Authentication
---
> Details our proposal of how to handle authentication.
We haven't tested this technique, so we should build a version to ensure it works.
I'm 100% sure there will be errors in what i've written here...
While auspice was designed to facilitate open data sharing and rapid dissemination of results, it may be necessary to authenticate certain datasets (or indeed the entire instance).
Auspice itself contains no authentication ability, but if you are running a server then it is possible -- and relatively simple -- to build in authentication.
## Using the server to verify cookies
![auth-cartoon](assets/authentication.svg)
The server can examine cookies sent with each API request (or, the request for `index.html`) to verify the status of a user.
This allows the server to examine the cookie and:
* deliver different avaialable datasets depending on the cookie
* accept or reject specific dataset requests depending on the cookie
* redirect requests to a custom authentication page (referred to as `login.html`)
* If this is from a request for `index.html` (i.e. you want to secure the entire site), then the redirect is simple
* For redirects from an API request, you may have to respond with a 302 or 303 redirect header.
It is this custom authentication page which can process a login and set a cookie appropriately.
As auspice is served from the same domain, the cookie should remain with all requests.
Implementing authentication is beyond the scope of this documentation, but we can recommend [PassportJS](http://www.passportjs.org) and [Auth0](https://auth0.com/), the latter of which allows you to easily use single-signin strategies.
---
title: Auspice Server API
title: Building a custom server for auspice
---
> This API is largely based off the interface used by nextstrain.
Most probably it will change dramatically over the coming weeks.
> This should be about the new API, assuming that I implement it!
The client (i.e. the auspice web page) makes requests to a server, for instance requesting a dataset file or requesting a listing of available datasets.
The server is referred to as "charon".
Currently the server needs to handle three requests (detailed below), which are made to the same domain as the client (this may be changeable in the future).
The Auspice client needs to make a number of requests to a server for:
* available datasets & narratives
* dataset JSON(s)
* Narrative markdown
For instance, when you run `auspice` locally, the default server scans a provided directory on your computer to create a list of available datasets, and delivers these files to the client for vizualisation when needed.
Auspice by itself includes handlers for these requests.
These handlers source data from the local filesystem so that running auspice without extensions can view locally available datasets.
## Why would I need to create a custom server?
Customisations of auspice can provide their own handlers, allowing for multiple different use cases.
For instance, **auspice.us** (currently located as a subdirectory of auspice) contains handlers to fetch datasets from github repos ("community" builds). The handlers used in **nextstrain.org** fetch datasets from S3 buckets.
> You might not need to! If all your URLs correspond directly to asset paths, or can be made to with a simple transform, then using auspice to [generate a static site](build-static/introduction.md) may be much easier.
* If you want to interpret URLs (perhaps to provide redirects), or deliver JSONs from different sources then a server might be needed.
For instance, nextstrain.org uses a server to access datasets stored on Amazon S3 buckets, and auspice.us uses a server to access community datasets on GitHub.
* If you want to generate datasets on the fly, or apply transformations to datasets.
For instance, this is how nextstrain.org is able to serve v1 JSONs -- it transforms them to v2 spec on the server.
## Providing custom API handlers to auspice's built-in server
> The following content is largely taken from the current v1 docs and needs to be update
## Where are these "handlers" used?
The default auspice server contains handlers for the 3 API endpoints --
* `getAvailable(req, res)` which processes requests from `/charon/getAvailable` to return a list of available datasets and narratives.
* `getDataset(req, res)` which processes requests from `/charon/getDataset` -- return the requested dataset
* `getNarrative(req, res)` which processes requests from `/charon/getNarrative` -- return the requested narrative
see [the API docs](build-server/api.md) for more information on these.
The `req` and `res` arguments are express objects (TODO: provide link).
Customisations of auspice can provide their own handlers, allowing for multiple different use cases.
For instance, **auspice.us** (currently located as a subdirectory of auspice) contains handlers to fetch datasets from github repos ("community" builds).
#### Where are these "handlers" used?
During development of auspice, the dev-server needs access to these handlers in order to make process requests.
Building of the auspice client (`auspice build ...`) doesn't need to know about these handlers, as the client will simply make requests to the API detailed below. (Currently this is different for serverless builds, see [github.com/blab/ZEBOV](https://github.com/blab/ZEBOV) for an example).
Serving the auspice client (`auspice view ...`), or whatever custom server implementation you design, will need to use these handlers.
Serving the auspice client (`auspice view ...`) will need to use these handlers.
## Providing these handlers to `auspice build` and `auspice view`
#### Providing these handlers to `auspice build` and `auspice view`
The handlers should be defined in a javascript file provided to those commands via the `--handlers` argument. This file should export three functions via:
```js
module.exports = {
......@@ -32,7 +54,9 @@ module.exports = {
getNarrative
};
```
Here's a pseudocode example of one of these functions.
```js
const getAvailable = (req, res) => {
try {
......@@ -48,53 +72,7 @@ const getAvailable = (req, res) => {
# API description
Currently the client makes three requests:
* `/charon/getAvailable` -- return a list of available datasets and narratives
* `/charon/getDataset` -- return the requested dataset
* `/charon/getNarrative` -- return the requested narrative
You can choose to handle these in your own server, or provide handlers to the auspice (dev-)server which are called whenever these requests are received (see above).
## get available datasets: `/charon/getAvailable`
Query arguments:
* `prefix` (optional) - the pathname of the requesting page in auspice.
Response shape:
```json
{
"datasets": [
{"request": "URL of a dataset. Will become the prefix in a getDataset request"},
...
],
"narratives": [
{"request": "URL of a narrative. Will become the prefix in a getNarrative request"},
...
]
}
```
## get a dataset: `/charon/getDataset`
Query arguments:
* `prefix` (required) - the pathname of the requesting page in auspice. Use this to determine which dataset to return.
* `deprecatedSecondTree` (optional) - deprecated.
* `type` (optional) -- if specified, then the request is for an additional file (e.g. "tip-frequencies"), not the main dataset.
Response shape:
> This needs to be updated to schema 2.0. These docs should point to the schema definitions (currently in the augur repo).
The current main dataset response shape is:
```json
{
"meta": "the schema 1.0 metadata json object",
"tree": "the schema 1.0 tree json object",
"_source": "the source (e.g. live, staging, github). Only used by the sidebar dataset selector",
"_url": "the URL to which auspice should update. Allows flu to redirect silently to flu/seasonal/..."
}
```
## Building a custom server
## get a narrative: `/charon/getNarrative`
> to do
TODO
\ No newline at end of file
---
title: Example of building a server
---
> Here i'm imagining a walk-through of how to create a basic server from scratch, including the API handlers and importing useful functions from `auspice`. Or, instead, perhaps easier is to use the provided auspice server with custom handlers.
\ No newline at end of file
---
title: API
---
> TODO
* Customisation config
* function to transform URLs
* config options to transform URLs (instead of a function)
* explination of `auspice build --static` and related
\ No newline at end of file
---
title: Generating a static site
---
> How this works is going to change a lot in the near future, but we could write docs about the basic idea.
Auspice can be made to generate static sites such as those hosted on github pages.
This makes things simple as you don't need to worry about writing a server!
While it is slightly more limited than a server build, it can be surprisingly versitile!
\ No newline at end of file
---
title: Creating a github pages instance
---
> TODO create a walkthrough going from having 1 or more (v2) JSONs to deploying a github pages site.
\ No newline at end of file
---
title: Improving documentation
---
> Do we want this in the docs? It's all on github so we could encourage PRs to fix things.
Could even create a button to automagicallly link to the markdown file behind each doc page.
---
title: Authentication
---
> Note that this page details our proposal of how to handle authentication.
Comments welcome.
We understand it may be necessary to authenticate the entire auspice website, or certain datasets.
Our proposed solution to this is to perform all authentication on the server (remember that custom server handlers are already part of the auspice extension framework).
This relies on cookies being available to the server on each and every request made from auspice, which should happen automatically.
## Logging in / authenticating:
The intial request (which currently serves ) shall check that the user is authenticaed.
If so, it can deliver the auspice `index.html`.
If not, it can redirect to a login page which will set this cookie.
Note that this login page is deliberately _not_ part of auspice.
The login details (e.g. username) could be available to auspice via the `getAvailable` request (_to explore_).
We will design a (customisable) login button / logged in user for auspice.
It may be that the "login" button redirects to `/login` which is handled by the server as above.
## Restricting datasets:
The datasets which are "available" to the client can be controlled by the server, such that only those with sufficient permissions are returned when the `getAvailable` request is processed.
Likewise, requests for `getDataset` can be checked against the current cookie.
---
title: Sidebar theming
---
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.
It is also passed to the nav bar component as the `theme` prop.
> This interface is very experimental and will change frequently. Perhaps we'll use https://refactoringui.com/previews/building-your-color-palette/ as a guide to both naming and the number of properties available here.
```json
{
"sidebarTheme": {
"background": "#F2F2F2",
"color": "#000",
"sidebarBoxShadow": "rgba(0, 0, 0, 0.2)",
"font-family": "Lato, Helvetica Neue, Helvetica, sans-serif",
"selectedColor": "#5097BA",
"unselectedColor": "#333"
}
}
```
---
title: Extending Auspice
---
It's possible to "extend" auspice and change the aesthetics and/or functionality.
This allows custom builds of auspice each with their own appearence.
[nextstrain.org](https://nextstrain.org) is one such custom build.
## Developing and building auspice with extensions.
Auspice has two forms of extensions:
### Client extensions
Customising the appearence and functionality of the client is achieved through code injection at build time.
The available customisations are accessed through a `<clientConfig>` JSON with the following properties:
* "splashComponent" -- see [custom components](client/componentInterfaces.md)
* "navbarComponent" -- see [custom components](client/componentInterfaces.md)
* "browserTitle" -- the page title (i.e. the name in the tab of the browser window)
* "sidebarTheme" -- see [visual themes](client/sidebarTheme.md)
* "entryPage" -- not yet documented
* "hardcodedDataPaths" -- not yet documented, see [these docs](server/charonAPI.md).
### Server extensions
The client makes a number of requests which can be dynamically handled.
Alternativly, the files can defined at build time such that no server is needed.
See [these docs](server/charonAPI.md) for how to define the `<serverHandlers>` javascript file.
### Developing & Building custom auspice versions
While it's possible to run these commands from the auspice source directory (using `node auspice.js ...`), it's preferable to run them from the repo containing the client / server customisations.
This requires `auspice` to be installed globally (see above).
```bash
## DEVELOPMENT
auspice develop --verbose --extend <clientConfig> --handlers <serverHandlers>
## BUILD
auspice build --verbose --extend <clientConfig>
## VIEW (using auspice server with custom handlers)
auspice view --verbose --handlers <serverHandlers> --customBuild
```
## Examples of customisations:
* Auspice.us -- _to do_
* Nextstrain -- [documentation](https://github.com/nextstrain/nextstrain.org/tree/whitelabel)
* ZEBOV (serverless) -- [documentation](https://github.com/blab/ZEBOV)
* Simulated viral outbreak for a ARTIC workshop in Ghana -- [here](https://artic-network.github.io/artic-workshop)
---
title: Deploying auspice without a server
---
> This API is experimental. Most probably it will change dramatically over the coming weeks.
## Serverless builds
You may also choose to forego the server and hardcode the paths to the datasets.
For an example of this see [github.com/blab/ZEBOV](https://github.com/blab/ZEBOV) -- specifically [this part](https://github.com/blab/ZEBOV/blob/master/auspiceCustomisations/config.json#L3) of the auspice config.
---
title: Injecting custom components
title: API
---
> These interfaces are very experimental and will change frequently.
Documentation is somewhat incomplete.
Please contact us (links at the bottom of the page) if you are using these customisations as we would like to develop them in a collaborative fashion.
> These will change 😱😱😱 this is taken from the v1 docs
## 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.
It is also passed to the nav bar component as the `theme` prop.
```json
{
"sidebarTheme": {
"background": "#F2F2F2",
"color": "#000",
"sidebarBoxShadow": "rgba(0, 0, 0, 0.2)",
"font-family": "Lato, Helvetica Neue, Helvetica, sans-serif",
"selectedColor": "#5097BA",
"unselectedColor": "#333"
}
}
```
# 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.
Right now this is only available for the splash page and nav-bar components, whose interfaces are defined here.
......@@ -46,6 +67,3 @@ Available props:
* `sidebar` boolean. Is it to be displayed in the sidebar?
The navbar also receives the (possibly customised) sidebar theme which can be used to style components.
---
title: Customising auspice
---
> This page needs to convey how important and powerful this functionality is.
Auspice (the client) allows one to customise the visual appearence.
This is how auspice.us and nextstrain.org/zika look different, despite both being built using auspice.
We do this by defining a set of customisations -- both functional and aesthetic -- which are overlaid during the compilation phase.
The available customisations are accessed through a `<clientConfig>` JSON which is used via `auspice develop --extend <json>` or `auspice build --extend <json>`. This properties allowed in this json include:
* `splashComponent`
* `navbarComponent`
* `browserTitle` -- the page title (i.e. the name in the tab of the browser window)
* `sidebarTheme`
* `entryPage`
* `hardcodedDataPaths`
See the [API docs](customise-client/api.md) for full details of each customisation, or read the [walk through](customise-client/walk-through.md) to see how we used these to create a custom version of auspice.
---
title: Creating custom instance
---
> TODO create a walkthrough of one such page -- best to use one which actually exists I think.
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment