diff --git a/DEV_DOCS.md b/DEV_DOCS.md index af737256a..229509987 100644 --- 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 index d4bb2cbb9..1518a91bb 100644 --- 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 index 45dbc6841..213d71ebe 100644 --- 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 index c019fb49c..6c1cbdac8 100644 --- 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",