Generate API docs as part of Sphinx's build process

This change has the benefit of supporting ReadTheDocs builds as
discussed in readthedocs/readthedocs.org#1139

.github/workflows/lint.yaml

@@ -47,7 +47,7 @@ jobs:
 
     - name: Generate and test API docs
       run: |
-        make apidocs html
+        make html
       env:
         SPHINXOPTS: "-n -v -W --keep-going"
       working-directory: ./docs

docs/Makefile

@@ -14,11 +14,6 @@ help:
 
 .PHONY: help Makefile
 
-
-apidocs:
-	git clean -fdx "$(SOURCEDIR)/ref"
-	sphinx-apidoc --ext-autodoc --ext-intersphinx --separate --implicit-namespaces --no-toc -o "$(SOURCEDIR)/ref" ../crate
-
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

docs/source/crate_operator_ext.py

@@ -14,13 +14,31 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+import pathlib
+
 from docutils.nodes import Element
 from sphinx.addnodes import pending_xref
 from sphinx.application import Sphinx
 from sphinx.environment import BuildEnvironment
 from sphinx.errors import NoUri
 
 
+def run_apidoc(_):
+    from sphinx.ext import apidoc
+
+    argv = [
+        "--ext-autodoc",
+        "--ext-intersphinx",
+        "--separate",
+        "--implicit-namespaces",
+        "--no-toc",
+        "-o",
+        str(pathlib.Path(__file__).parent / "ref"),
+        str(pathlib.Path(__file__).parent.parent.parent / "crate"),
+    ]
+    apidoc.main(argv)
+
+
 def missing_reference(
     app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Element
 ) -> Element:
@@ -49,4 +67,5 @@ def missing_reference(
 
 
 def setup(app):
+    app.connect("builder-inited", run_apidoc)
     app.connect("missing-reference", missing_reference)