Commit API docs and generate them using a separate task. (#48)

y-scope · Mar 15, 2024 · 50396dc · 50396dc
1 parent 7019e7f
commit 50396dc
Show file tree

Hide file tree

Showing 9 changed files with 111 additions and 9 deletions.
diff --git a/docs/README.md b/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

diff --git a/docs/src/api/clp_ffi_py.ir.native.rst b/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:
diff --git a/docs/src/api/clp_ffi_py.ir.query_builder.rst b/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:
diff --git a/docs/src/api/clp_ffi_py.ir.readers.rst b/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:
diff --git a/docs/src/api/clp_ffi_py.ir.rst b/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:
diff --git a/docs/src/api/clp_ffi_py.rst b/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:
diff --git a/docs/src/api/clp_ffi_py.utils.rst b/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:
diff --git a/docs/src/api/clp_ffi_py.wildcard_query.rst b/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:
diff --git a/docs/tasks.yml b/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)
       - |-