Enable autodoc & sphinx-apidoc for nv-ingest, nv-ingest-api, and nv-i…

…ngest-client (#477)
NVIDIA · Feb 20, 2025 · 68d1c57 · 68d1c57
1 parent ff5d9da
commit 68d1c57
Show file tree

Hide file tree

Showing 11 changed files with 71 additions and 109 deletions.
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -43,21 +43,11 @@ jobs:
           . venv/bin/activate
           pip install -r docs/requirements.txt
 
-      - name: Build Sphinx API Docs
+      - name: Build Docs using Makefile
         run: |
           . venv/bin/activate
-          cd api
-          pip install -e .
-          cd ../
-          cd docs/sphinx_docs
-          make html
-          cd ../../
-          mv docs/sphinx_docs/build/html docs/docs/user-guide/api_docs
-
-      - name: Build MkDocs Site
-        run: |
-          . venv/bin/activate
-          mkdocs build --config-file docs/mkdocs.yml
+          cd docs
+          make docs
 
       - name: Upload Site Artifacts
         uses: actions/upload-pages-artifact@v3

diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Define paths
+SPHINX_BUILD_DIR=sphinx_docs/build
+SPHINX_SOURCE_DIR=sphinx_docs/source
+SPHINX_OUTPUT_DIR=docs/user-guide/developer-guide/api-docs
+
+# Default target
+.PHONY: all
+all: docs
+
+# Run apidoc against nv-ingest, nv-ingest-api, and nv-ingest-client codebase
+.PHONY: sphinx-apidoc
+sphinx-apidoc:
+	@echo "🏃 Running sphinx-apidoc against nv-ingest"
+	sphinx-apidoc -o sphinx_docs/source/nv-ingest ../src/nv_ingest
+
+	@echo "🏃 Running sphinx-apidoc against nv-ingest-api"
+	sphinx-apidoc -o sphinx_docs/source/nv-ingest-api ../api/src/nv_ingest_api
+
+	@echo "🏃 Running sphinx-apidoc against nv-ingest-client"
+	sphinx-apidoc -o sphinx_docs/source/nv-ingest-client ../client/src/nv_ingest_client
+
+# Build Sphinx documentation
+.PHONY: sphinx
+sphinx:
+	@echo "📖 Building Sphinx documentation..."
+	sphinx-build -b html $(SPHINX_SOURCE_DIR) $(SPHINX_BUILD_DIR)/html
+
+# Copy Sphinx HTML output to the final location
+.PHONY: copy-sphinx
+copy-sphinx: sphinx
+	@echo "📂 Copying Sphinx docs to $(SPHINX_OUTPUT_DIR)..."
+	mkdir -p $(SPHINX_OUTPUT_DIR)
+	cp -r $(SPHINX_BUILD_DIR)/html/* $(SPHINX_OUTPUT_DIR)/
+
+# Run MkDocs to build final documentation
+.PHONY: mkdocs
+mkdocs:
+	@echo "📚 Building MkDocs site..."
+	mkdocs build
+
+# Full docs pipeline
+.PHONY: docs
+docs: sphinx-apidoc sphinx copy-sphinx mkdocs
+	@echo "✅ Documentation build complete!"
+
+# Clean up built docs
+.PHONY: clean
+clean:
+	@echo "🧹 Cleaning up built documentation..."
+	rm -rf $(SPHINX_BUILD_DIR) $(SPHINX_OUTPUT_DIR) site
diff --git a/docs/docs/user-guide/SUMMARY.md b/docs/docs/user-guide/SUMMARY.md
@@ -3,5 +3,4 @@
 - [Quickstart](quickstart-guide.md)
 - [Developer Guide](developer-guide/)
 - [Contributing](contributing.md)
-- [API Reference](api_docs/)
 - [Release Notes](releasenotes-nv-ingest.md)
diff --git a/docs/docs/user-guide/developer-guide/SUMMARY.md b/docs/docs/user-guide/developer-guide/SUMMARY.md
@@ -4,5 +4,6 @@
 - [Environment Configuration Variables](environment-config.md)
 - [Developing with Kubernetes](kubernetes-dev.md)
 - [NV-Ingest Command Line (CLI)](nv-ingest_cli.md)
+- [API Reference](api-docs)
 - [Telemetry](telemetry.md)
 - [Environment Configuration Variables](environment-config.md)
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -8,6 +8,7 @@ mkdocs-jupyter
 mkdocs-include-dir-to-nav
 mkdocs-literate-nav
 mkdocs-site-urls
+myst-parser
 sphinx
 sphinx-markdown-builder
 sphinx-rtd-theme
diff --git a/docs/sphinx_docs/source/conf.py b/docs/sphinx_docs/source/conf.py
@@ -6,6 +6,8 @@
 import sys
 
 sys.path.insert(0, os.path.abspath("../../../api/src"))  # nv-ingest-api src
+sys.path.insert(1, os.path.abspath("../../../client/src"))  # nv-ingest-client src
+sys.path.insert(2, os.path.abspath("../../../src"))  # nv-ingest src
 
 project = "nv-ingest"
 copyright = "2025, Nvidia"
@@ -16,6 +18,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+    "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",

diff --git a/docs/sphinx_docs/source/index.rst b/docs/sphinx_docs/source/index.rst
@@ -1,10 +1,13 @@
-NV-Ingest documentation
-=======================
+===============
+API reference
+===============
 
-Add a welcome message here .....
+Provides API references for the `nv-ingest-api`, `nv-ingest-client`, and `nv-ingest` modules. 
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+    :maxdepth: 2
+    :caption: NV-Ingest Packages
 
-   user_guide/index
+    nv-ingest-api/modules.rst
+    nv-ingest-client/modules.rst
+    nv-ingest/modules.rst
diff --git a/...cs/api/api/nv_ingest_api.primitives.control_message_task.ControlMessageTask.rst b/...cs/api/api/nv_ingest_api.primitives.control_message_task.ControlMessageTask.rst
diff --git a/docs/sphinx_docs/source/user_guide/api_docs/api/primitives.rst b/docs/sphinx_docs/source/user_guide/api_docs/api/primitives.rst
diff --git a/docs/sphinx_docs/source/user_guide/api_docs/index.rst b/docs/sphinx_docs/source/user_guide/api_docs/index.rst
diff --git a/docs/sphinx_docs/source/user_guide/index.rst b/docs/sphinx_docs/source/user_guide/index.rst