Commit API docs and generate them using a separate task.

docs/README.md

@@ -21,14 +21,29 @@ documentation website for this package:
   ```
 
   * The output of the build will be in `../build/docs/html`.
-  * API reference docs will be written to `src/api`.
 
 * Clean up the build:
 
   ```shell
   task docs:clean
   ```
 
+* Generate API docs:
+
+  ```shell
+  task docs:api-docs
+  ```
+
+  * This will regenerate the API docs in `src/api`. You should run this whenever you change the
+    modules or package that exist in `clp-ffi-py`, and then commit the changes.
+  * This will overwrite any existing API doc files. This is only a problem if any of the previously
+    generated files were manually customized (e.g., to reformat some docs). You should
+    review the changes carefully to make sure any customizations have not been mistakenly deleted.
+  * This will *not* remove docs for packages/modules that no longer exist. You should make sure to
+    delete those docs from `src/api`. In addition, ensure that:
+    * in the case of a rename, any previous customizations are retained.
+    * no unrelated files (e.g., indexes) are deleted.
+
 ## Viewing the Output
 
 ```shell

docs/src/api/clp_ffi_py.ir.native.rst

@@ -0,0 +1,7 @@
+clp\_ffi\_py.ir.native module
+=============================
+
+.. automodule:: clp_ffi_py.ir.native
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src/api/clp_ffi_py.ir.query_builder.rst

@@ -0,0 +1,7 @@
+clp\_ffi\_py.ir.query\_builder module
+=====================================
+
+.. automodule:: clp_ffi_py.ir.query_builder
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src/api/clp_ffi_py.ir.readers.rst

@@ -0,0 +1,7 @@
+clp\_ffi\_py.ir.readers module
+==============================
+
+.. automodule:: clp_ffi_py.ir.readers
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src/api/clp_ffi_py.ir.rst

@@ -0,0 +1,20 @@
+clp\_ffi\_py.ir package
+=======================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   clp_ffi_py.ir.native
+   clp_ffi_py.ir.query_builder
+   clp_ffi_py.ir.readers
+
+Module contents
+---------------
+
+.. automodule:: clp_ffi_py.ir
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src/api/clp_ffi_py.rst

@@ -0,0 +1,27 @@
+clp\_ffi\_py package
+====================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   clp_ffi_py.ir
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   clp_ffi_py.utils
+   clp_ffi_py.wildcard_query
+
+Module contents
+---------------
+
+.. automodule:: clp_ffi_py
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src/api/clp_ffi_py.utils.rst

@@ -0,0 +1,7 @@
+clp\_ffi\_py.utils module
+=========================
+
+.. automodule:: clp_ffi_py.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/src/api/clp_ffi_py.wildcard_query.rst

@@ -0,0 +1,7 @@
+clp\_ffi\_py.wildcard\_query module
+===================================
+
+.. automodule:: clp_ffi_py.wildcard_query
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/tasks.yml

@@ -11,6 +11,19 @@ vars:
     sh: python3 -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')"
 
 tasks:
+  api-docs:
+    dir: "{{.TASKFILE_DIR}}"
+    deps: [ "docs-venv" ]
+    cmds:
+      - |-
+        . "{{.DOCS_VENV_DIR}}/bin/activate"
+        sphinx-apidoc \
+          --separate \
+          --no-toc \
+          --force \
+          -o src/api \
+          "{{.DOCS_VENV_DIR}}/lib/python{{.PYTHON_VERSION}}/site-packages/clp_ffi_py/"
+
   clean:
     cmds:
       - "rm -rf '{{.DOCS_BUILD_DIR}}'"
@@ -31,14 +44,6 @@ tasks:
     cmds:
       - |-
         . "{{.DOCS_VENV_DIR}}/bin/activate"
-
-        sphinx-apidoc \
-        --force \
-        --separate \
-        --no-toc \
-        -o src/api \
-        "{{.DOCS_VENV_DIR}}/lib/python{{.PYTHON_VERSION}}/site-packages/clp_ffi_py/"
-
         sphinx-build -a -c conf -b html src "{{.OUTPUT_DIR}}"
       # Checksum the generated files (this command must be last)
       - |-