Merge pull request #1609 from nextstrain/victorlin/docs/autobuild

Improve docs development experience
nextstrain · Dec 6, 2022 · ad5a1b3 · ad5a1b3
2 parents 7e47c1e + 377d821
commit ad5a1b3
Show file tree

Hide file tree

Showing 4 changed files with 22 additions and 2 deletions.
diff --git a/DEV_DOCS.md b/DEV_DOCS.md
@@ -131,7 +131,24 @@ The main Nextstrain documentation is available at [docs.nextstrain.org](https://
 
 The Auspice technical reference guide is available at [docs.nextstrain.org/projects/auspice](https://docs.nextstrain.org/projects/auspice/en/stable/index.html). That documentation is built from the files in this repo in the `./docs` folder.
 
-To build the Auspice documentation locally, run `npm run build-docs` and open `docs/_build/html/index.html`.
+To preview the Auspice documentation locally,
+
+1. Create and activate a Conda environment from `docs/environment.yml`. Example using Mamba:
+
+    ```bash
+    mamba env create --file docs/environment.yml
+    conda activate auspice-docs
+    ```
+
+2. Build the docs from a clean slate.
+
+    ```bash
+    make -C docs clean livehtml
+    ```
+
+3. Open the preview link (http://127.0.0.1:8000) in a browser.
+
+Changes to documentation source files (`.md` and `.rst` files under `docs/`) should automatically be reflected upon page refresh.
 
 ## Contributing to Internationalization and Localization (i18n/l18n)
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -18,3 +18,6 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -8,5 +8,6 @@ dependencies:
   - pip
   - pip:
     - nextstrain-sphinx-theme>=2022.5
+    - sphinx-autobuild
     - sphinx-markdown-tables
     - sphinx-argparse
diff --git a/package.json b/package.json
@@ -26,7 +26,6 @@
     "get-data": "env bash ./scripts/get-data.sh",
     "heroku-postbuild": "npm run build && npm run get-data",
     "gzip-and-upload": "env bash ./scripts/gzip-and-upload.sh",
-    "build-docs": "cd docs && make clean && make html && echo 'Docs rebuild, open docs/_build/html/index.html'",
     "test": "jest test/*.js",
     "integration-test": "NODE_ENV=test ENV=dev jest ./test/integration/*.js --config puppeteer.config.js",
     "integration-test:ci": "start-server-and-test server http://localhost:4000 integration-test",