Align local docs builds with Read the Docs apidoc

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.

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
 

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.