diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 9ba4b01..3346620 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -114,6 +114,11 @@ The project provides several ``make`` targets to help with development: * ``make test`` - Run the test suite with pytest using the default Python version. For testing across multiple Python versions, use ``tox`` instead. +* ``make docs`` / ``make docs-ci`` - Build the Sphinx documentation locally (with + warnings treated as errors). API stub pages are generated with + ``python -m sphinx.ext.apidoc`` against the ``multibase`` package, matching + the Read the Docs ``pre_build`` job. + * ``make pr`` - Run a complete pre-PR check: clean build artifacts, fix formatting, run linting, type checking, and tests. This is the recommended command to run before submitting a pull request. diff --git a/Makefile b/Makefile index 381aa6e..7b67b9c 100644 --- a/Makefile +++ b/Makefile @@ -67,7 +67,7 @@ test: docs-ci: rm -f docs/multibase.rst rm -f docs/modules.rst - sphinx-apidoc -o docs/ multibase + python -m sphinx.ext.apidoc -o docs/ multibase $(MAKE) -C docs clean mkdir -p docs/_static $(MAKE) -C docs html SPHINXOPTS="-W" @@ -92,8 +92,11 @@ validate-newsfragments: towncrier build --draft --version preview build-docs: - sphinx-apidoc -o docs/ . "*conftest*" tests/ + rm -f docs/multibase.rst + rm -f docs/modules.rst + python -m sphinx.ext.apidoc -o docs/ multibase $(MAKE) -C docs clean + mkdir -p docs/_static $(MAKE) -C docs html $(MAKE) -C docs doctest diff --git a/newsfragments/31.docs.rst b/newsfragments/31.docs.rst new file mode 100644 index 0000000..918ea91 --- /dev/null +++ b/newsfragments/31.docs.rst @@ -0,0 +1 @@ +Aligned local documentation builds with Read the Docs by using ``python -m sphinx.ext.apidoc`` for the ``multibase`` package.