draft v2 docs

Implement much improved splash page and create framework for docs pages (including new tutorial section). Individual doc pages are mostly incomplete.

docs-src/README.md

@@ -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):

docs-src/docs/auspice-us/community-builds.md

@@ -0,0 +1,38 @@
+---
+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:[email protected])
+
+
+## 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
+* 😳

docs-src/docs/auspice-us/introduction.md

@@ -0,0 +1,9 @@
+---
+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.

docs-src/docs/build-server/api.md

@@ -0,0 +1,49 @@
+---
+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

docs-src/docs/build-server/authentication.md

@@ -0,0 +1,38 @@
+---
+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.
+
+
+
+
+

docs-src/docs/build-server/introduction.md

@@ -0,0 +1,78 @@
+---
+title: Building a custom server for auspice
+---
+
+> This should be about the new API, assuming that I implement it!
+
+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.
+
+
+## Why would I need to create a custom server?
+
+> 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
+
+
+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 ...`) will need to use these handlers.
+
+#### 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 = {
+  getAvailable,
+  getDataset,
+  getNarrative
+};
+```
+
+Here's a pseudocode example of one of these functions.
+
+```js
+const getAvailable = (req, res) => {
+  try {
+    /* collect available data */
+    res.json(data);
+  } catch (err) {
+    res.statusMessage = `error message to display in client`;
+    console.log(res.statusMessage); /* printed by the server */
+    return res.status(500).end();
+  }
+};
+```
+
+
+
+
+## Building a custom server
+
+TODO

docs-src/docs/build-server/walk-through.md

@@ -0,0 +1,5 @@
+---
+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. 

docs-src/docs/build-static/api.md

@@ -0,0 +1,11 @@
+---
+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

docs-src/docs/build-static/introduction.md

@@ -0,0 +1,9 @@
+---
+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!

docs-src/docs/build-static/walk-through.md

@@ -0,0 +1,5 @@
+---
+title: Creating a github pages instance
+---
+
+> TODO create a walkthrough going from having 1 or more (v2) JSONs to deploying a github pages site.

docs-src/docs/contributing/documentation.md

@@ -0,0 +1,6 @@
+---
+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.