diff --git a/.github/workflows/lint-test.yml b/.github/workflows/lint-test.yml index 8dbf4e9..65594af 100644 --- a/.github/workflows/lint-test.yml +++ b/.github/workflows/lint-test.yml @@ -49,7 +49,7 @@ jobs: run: invoke benchmark - name: sphinx build 🐪 - run: invoke doc + run: invoke build - name: check-manifest 📰 run: check-manifest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7d3054a..bd2bf7e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -25,7 +25,7 @@ jobs: pip install .[dev] build twine - name: Build documentation with Sphinx 🐪 - run: invoke doc + run: invoke build - name: Deploy documentation 🚀 uses: JamesIves/github-pages-deploy-action@4.1.5 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c573ae6..b163371 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,10 +79,14 @@ The relevant files are in `docs/`: - `index.md`: Landing documentation page. It includes the `README.md`. - `reference.md`: Generates API documentation for `content` and `encoders` modules using [sphinx.ext.autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). -The documentation can be build locally using +To build the documentation in development, with live reload at http://127.0.0.1:8000/, run: ``` invoke doc ``` -The HTML pages will be generated in `_build`. +To build the documentation once into the `_build` folder, run: + +``` +invoke build +``` \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index c2cc8ce..656cbc6 100644 --- a/setup.cfg +++ b/setup.cfg @@ -55,6 +55,7 @@ dev = pytest-tornado sphinx sphinx-argparse + sphinx-autobuild h5grove[tornado] types-contextvars types-dataclasses diff --git a/tasks.py b/tasks.py index 47e5714..01f0819 100644 --- a/tasks.py +++ b/tasks.py @@ -43,8 +43,16 @@ def test(c, verbose=False, keyword="", cov_lines=False): @task -def doc(c): +def build(c): """Sphinx build""" result = c.run(f"{sys.executable} -m sphinx -W -b html docs _build") if result.exited != 0: raise SystemExit(result.exited) + + +@task +def doc(c): + """Sphinx autobuild""" + result = c.run(f"{sys.executable} -m sphinx_autobuild -W -b html docs _build") + if result.exited != 0: + raise SystemExit(result.exited)