CI driven github pages with sphinx docs for api reference (NVIDIA#459)

.github/workflows/build-docs.yml

@@ -26,7 +26,18 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r docs/requirements.txt
 
-      # Builds docs site
-      - name: Build docs site
+      - name: Build Sphinx API Docs
         run: |
-          mkdocs build --config-file docs/mkdocs.yml
+          cd docs/sphinx_docs
+          make html
+          cd ../../
+          mv docs/sphinx_docs/build/html docs/docs/user-guide/api_docs
+
+      - name: Build MkDocs Site
+        run: mkdocs build --config-file docs/mkdocs.yml
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

docs/docs/user-guide/SUMMARY.md

@@ -3,4 +3,5 @@
 - [Quickstart](quickstart-guide.md)
 - [Developer Guide](developer-guide/)
 - [Contributing](contributing.md)
+- [API Reference](api_docs/)
 - [Release Notes](releasenotes-nv-ingest.md)

docs/mkdocs.yml

@@ -1,6 +1,6 @@
-site_name: MyLibrary Documentation
+site_name: NV-Ingest Documentation
 # site_url:
-# repo_url:
+repo_url: https://github.com/NVIDIA/nv-ingest
 # repo_name:
 
 theme:
@@ -57,8 +57,12 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
+          options:
+            docstring_style: google
+            show_source: true
+            show_if_no_docstring: true
           paths:
-            - ../sub-packages/*/src
+            - ../api/*/src/nv_ingest_api
   - mkdocs-jupyter:
       theme: auto
       highlight_extra_classes: "jupyter-notebook"

docs/requirements.txt

@@ -8,3 +8,5 @@ mkdocs-jupyter
 mkdocs-include-dir-to-nav
 mkdocs-literate-nav
 mkdocs-site-urls
+sphinx
+sphinx-rtd-theme

docs/sphinx_docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/sphinx_docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/sphinx_docs/source/conf.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../../../api/src"))  # nv-ingest-api src
+
+project = "nv-ingest"
+copyright = "2025, Nvidia"
+author = "Nvidia"
+release = "24.12"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

docs/sphinx_docs/source/index.rst

@@ -0,0 +1,10 @@
+NV-Ingest documentation
+=======================
+
+Add a welcome message here .....
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   user_guide/index

docs/sphinx_docs/source/user_guide/api_docs/api/api/nv_ingest_api.primitives.control_message_task.ControlMessageTask.rst

@@ -0,0 +1,58 @@
+nv\_ingest\_api.primitives.control\_message\_task.ControlMessageTask
+====================================================================
+
+.. currentmodule:: nv_ingest_api.primitives.control_message_task
+
+.. autoclass:: ControlMessageTask
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~ControlMessageTask.__init__
+      ~ControlMessageTask.construct
+      ~ControlMessageTask.copy
+      ~ControlMessageTask.dict
+      ~ControlMessageTask.from_orm
+      ~ControlMessageTask.json
+      ~ControlMessageTask.model_construct
+      ~ControlMessageTask.model_copy
+      ~ControlMessageTask.model_dump
+      ~ControlMessageTask.model_dump_json
+      ~ControlMessageTask.model_json_schema
+      ~ControlMessageTask.model_parametrized_name
+      ~ControlMessageTask.model_post_init
+      ~ControlMessageTask.model_rebuild
+      ~ControlMessageTask.model_validate
+      ~ControlMessageTask.model_validate_json
+      ~ControlMessageTask.model_validate_strings
+      ~ControlMessageTask.parse_file
+      ~ControlMessageTask.parse_obj
+      ~ControlMessageTask.parse_raw
+      ~ControlMessageTask.schema
+      ~ControlMessageTask.schema_json
+      ~ControlMessageTask.update_forward_refs
+      ~ControlMessageTask.validate
+
+
+
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~ControlMessageTask.model_computed_fields
+      ~ControlMessageTask.model_config
+      ~ControlMessageTask.model_extra
+      ~ControlMessageTask.model_fields
+      ~ControlMessageTask.model_fields_set
+      ~ControlMessageTask.name
+      ~ControlMessageTask.id
+      ~ControlMessageTask.properties
+
+

docs/sphinx_docs/source/user_guide/api_docs/api/primitives.rst

@@ -0,0 +1,11 @@
+=========
+Primitives
+=========
+.. currentmodule:: nv_ingest_api.primitives.control_message_task
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+   :toctree: api/
+
+   ControlMessageTask

docs/sphinx_docs/source/user_guide/api_docs/index.rst

@@ -0,0 +1,14 @@
+.. nv-ingest-api:
+
+=============
+API reference
+=============
+
+This page provides a list of all publicly accessible modules, methods and classes through
+``nv-ingest-api.*`` namespace.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: API Documentation
+
+    api/primitives

docs/sphinx_docs/source/user_guide/index.rst

@@ -0,0 +1,6 @@
+
+.. toctree::
+    :maxdepth: 2
+    :caption: nv-ingest User Guide
+
+    api_docs/index