diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56734ab1..762f82c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -167,20 +167,19 @@ We recommend that your contribution complies with the following guidelines befor ## Building the documentation locally -A local build of the docs is achieved by: +To build the documentation, run from the **project root**: ```bash -cd docs make html ``` - -Sometimes not all changes are recognised. In that case run this (again from within the `docs` folder): - +To clean and rebuild the documentation from scratch: ```bash -make clean && make html +make cleandocs +make html ``` + Docs are built in docs/_build/html, but these docs are not committed to the GitHub repository due to .gitignore. -Docs are built in `docs/_build`, but these docs are _not_ committed to the GitHub repository due to `.gitignore`. + 📌 Note: The previous docs/Makefile has been removed. Please use only the root-level Makefile for documentation commands ## Overview of code structure diff --git a/Makefile b/Makefile index 352f8a09..9f2b1971 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: init lint check_lint test +.PHONY: init lint check_lint test uml html cleandocs init: python -m pip install -e . --no-deps @@ -20,3 +20,12 @@ test: uml: pyreverse -o png causalpy --output-directory docs/source/_static --ignore tests + +# Docs build commands + +html: + sphinx-build -b html docs/source docs/_build + +cleandocs: + rm -rf docs/_build + rm -rf docs/source/api/generated diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 92dd33a1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)