move docusaurus dependency to docs-src sub-repo

Added npm scripts to make building the documentation easier (see `docs-src/README.md`)
Updated docusaurus to 1.8 and tested.
Note: for the `npm run build` command, on MacOS `cp` cannot be run with the `-avr` flags as previously included in `build-docs.sh`.

.gitignore

@@ -8,10 +8,6 @@ s3/
 /local_narratives/
 /narratives/
 
-## docs
-build/
-i18n/
-
 ### OSX ###
 .DS_Store
 

docs-src/.gitignore

@@ -0,0 +1,3 @@
+## docs
+build/
+i18n/

docs-src/README.md

@@ -1,27 +1,39 @@
 # Auspice Documentation
 
 This folder contains the static site generator and the markdown files which form the auspice documentation website.
-This is currently designed to be served from github pages.
+This is currently designed to be served from GitHub pages using the `auspice/docs` folder.
 [Docusaurus](https://docusaurus.io/) is used to generate the static site.
 
-### Folder structure:
+### Folder structure of `auspice/docs-src/`
 * `README.md` this file
-* `docs/` contains the raw markdown files. The filenames (and directory names) will be used as URLS.
+* `docs/` contains the raw markdown files. The filenames (and directory names) will be used as URLs.
+New pages here should also be added to `sidebars.json`.
 * `website/` the files needed to build the website.
-  * `website/sidebars.json` define the doc links in the sidebar
-  * `website/pages/index.js` the splash page
+  * `./sidebars.json` define the doc links in the sidebar
+  * `./pages/index.js` the splash page
+  * `./siteConfig.js` docusarus configuration - [see docs here](https://docusaurus.io/docs/en/site-config)
 
-### How to develop:
+
+## How to run 
+
+All commands run from this directory (`docs-src`).
+
+#### Installing dependencies
 ```bash
-cd website
-npx docusaurus-start
+npm install
 ```
 
-### How to deploy:
+#### Developing (live reloading etc):
+```bash
+npm run develop
+```
+
+#### (re-)build the static site
 
 ```bash
-cd website
-npx docusaurus-build # creates website/build/*
-cd ..
-cp -r website/build/auspice/* ../docs
+npm run build
 ```
+> This command will modify the files in `../docs/` which is where the GitHub pages site is served from.
+
+#### Deploy
+Once changes are merged into the master branch and pushed to GitHub the changes will be live.

docs-src/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "auspice-documentation",
+  "version": "1.0.0",
+  "description": "source files for auspice documentation",
+  "author": "James Hadfield",
+  "license": "AGPL-3.0-only",
+  "scripts": {
+    "develop": "cd website && docusaurus-start",
+    "build": "cd website && docusaurus-build && npm run removeBuiltDocs && cp -r ./build/auspice/* ../../docs && npm run makeReadme",
+    "build-docs": "npm run build",
+    "removeBuiltDocs": "rimraf ../docs/*",
+    "makeReadme": "echo '# Auspice built documentation to be served by GitHub pages.\\n\\nFiles in this folder should not be modified by hand, they are the generated from within the `docs-src` directory.' > ../docs/README.md"
+  },
+  "devDependencies": {
+    "docusaurus": "^1.8.1",
+    "rimraf": "^2.6.3"
+  }
+}

package.json

@@ -28,7 +28,7 @@
     "redeploy-site": "./scripts/redeploy-site.sh",
     "rebuild-docker-image": "./scripts/rebuild-docker-image.sh",
     "gzip-and-upload": "./scripts/gzip-and-upload.sh",
-    "build-docs": "./scripts/build-docs.sh"
+    "build-docs": "echo 'see ./docs-src/README.md'"
   },
   "dependencies": {
     "@babel/core": "^7.3.4",
@@ -68,7 +68,6 @@
     "d3-timer": "^1.0.7",
     "d3-transition": "^1.2.0",
     "d3-zoom": "^1.1.3",
-    "docusaurus": "^1.7.2",
     "es6-object-assign": "^1.1.0",
     "es6-promise": "~1.0.0",
     "es6-promise-polyfill": "^1.2.0",
@@ -109,7 +108,6 @@
     "redux-devtools": "^3.5.0",
     "redux-thunk": "^2.3.0",
     "request": "^2.87.0",
-    "rimraf": "^2.4.3",
     "run-sequence": "~0.3.6",
     "style-loader": "^0.13.2",
     "styled-components": "^4.0.3",

scripts/build-docs.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-base="$(dirname $0)/.."
-cd "$base"
-
-pushd docs-src/website
-docusaurus-build
-popd
-
-cp -avr docs-src/website/build/auspice/* docs/