From 288aa96ce1b5afc02ed721260e2745ca9d82f92e Mon Sep 17 00:00:00 2001
From: Markus Holtermann <markus@crate.io>
Date: Wed, 30 Sep 2020 12:57:09 +0200
Subject: [PATCH] Generate API docs as part of Sphinx's build process

This change has the benefit of supporting ReadTheDocs builds as
discussed in https://github.com/readthedocs/readthedocs.org/issues/1139
---
 .github/workflows/lint.yaml       |  2 +-
 docs/Makefile                     |  5 -----
 docs/source/crate_operator_ext.py | 17 +++++++++++++++++
 3 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
index 5e4c41b6..01d19f66 100644
--- a/.github/workflows/lint.yaml
+++ b/.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
diff --git a/docs/Makefile b/docs/Makefile
index a7f0019c..d0c3cbf1 100644
--- a/docs/Makefile
+++ b/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
diff --git a/docs/source/crate_operator_ext.py b/docs/source/crate_operator_ext.py
index 041db085..44ff2175 100644
--- a/docs/source/crate_operator_ext.py
+++ b/docs/source/crate_operator_ext.py
@@ -21,6 +21,22 @@
 from sphinx.errors import NoUri
 
 
+def run_apidoc(_):
+    from sphinx.ext import apidoc
+
+    argv = [
+        "--ext-autodoc",
+        "--ext-intersphinx",
+        "--separate",
+        "--implicit-namespaces",
+        "--no-toc",
+        "-o",
+        "source/ref",
+        "../crate",
+    ]
+    apidoc.main(argv)
+
+
 def missing_reference(
     app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Element
 ) -> Element:
@@ -49,4 +65,5 @@ def missing_reference(
 
 
 def setup(app):
+    app.connect("builder-inited", run_apidoc)
     app.connect("missing-reference", missing_reference)