docs: Generate API reference using sphinx-autoapi (#14)

* pyproject.toml: Add docs dependency group

* Update poetry.lock

* waveform: Fix bulleted list formatting

* docs: Add configuration and index page

* github: Update check_nitypes.yml to generate docs

* Remove Py3.8 Sphinx versioning

* Update poetry.lock

* github: Upload an artifact containing the generated docs

* github: Split check_docs into a separate workflow file so it doesn't gate tests

* waveform: Document warnings with "Raises" because "Warnings" displays a warning symbol

* docs: Add GitHub issue link to TODO

* pyproject.toml: Upgrade to latest Sphinx

* Update poetry.lock

* docs: Update copyright to use range of years

Author: bkeryan

.github/workflows/CI.yml

@@ -10,8 +10,11 @@ on:
 
 jobs:
   check_nitypes:
-    name: Check
+    name: Check nitypes
     uses: ./.github/workflows/check_nitypes.yml
+  check_docs:
+    name: Check docs
+    uses: ./.github/workflows/check_docs.yml
   run_unit_tests:
     name: Run unit tests
     uses: ./.github/workflows/run_unit_tests.yml

.github/workflows/check_docs.yml

@@ -0,0 +1,42 @@
+name: Check docs
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+env:
+  POETRY_VERSION: 1.8.2
+  PYTHON_VERSION: 3.11.9
+
+jobs:
+  check_docs:
+    name: Check docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        id: setup-python
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Set up Poetry
+        uses: Gr1N/setup-poetry@v9
+        with:
+          poetry-version: ${{ env.POETRY_VERSION }}
+      - name: Check for lock changes
+        run: poetry check --lock
+      - name: Cache virtualenv (with docs)
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: nitypes-with-docs-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('poetry.lock') }}
+      - name: Install nitypes (with docs)
+        run: poetry install -v --with docs
+      - name: Generate docs
+        run:  poetry run sphinx-build docs docs/_build -b html -W --keep-going
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: nitypes-docs
+          path: docs/_build/

docs/conf.py

@@ -0,0 +1,93 @@
+"""Sphinx Configuration File."""
+
+import datetime
+import pathlib
+
+import autoapi.extension
+import toml
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "autoapi.extension",
+    "m2r2",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+root_path = pathlib.Path(__file__).parent.parent
+pyproj_file = root_path / "pyproject.toml"
+proj_config = toml.loads(pyproj_file.read_text())
+
+
+project = proj_config["tool"]["poetry"]["name"]
+company = "National Instruments"
+copyright = f"2025-%Y, {company}"
+if datetime.datetime.now().year == 2025:
+    copyright = f"%Y, {company}"
+
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+version = proj_config["tool"]["poetry"]["version"]
+release = ".".join(version.split(".")[:2])
+description = proj_config["tool"]["poetry"]["description"]
+
+
+htmlhelp_basename = f"{project}doc"
+
+
+# tell autoapi to doc the public options
+autoapi_options = list(autoapi.extension._DEFAULT_OPTIONS)
+autoapi_options.remove("private-members")  # note: remove this to include "_" members in docs
+autoapi_dirs = [root_path / "src" / "nitypes"]
+autoapi_type = "python"
+autodoc_typehints = "description"
+
+
+# TODO: https://github.com/ni/nitypes-python/issues/16 - Update nitypes-python docs to use
+# :canonical: to resolve aliases (once supported by sphinx-autoapi)
+def skip_aliases(app, what, name, obj, skip, options):
+    """Skip documentation for classes that are exported from multiple modules."""
+    # For names that are defined in a private sub-module and aliased into a
+    # public package, hide the definition.
+    if name.startswith("nitypes.time._") or name.startswith("nitypes.waveform._"):
+        skip = True
+
+    return skip
+
+
+def setup(sphinx):
+    """Sphinx setup callback."""
+    sphinx.connect("autoapi-skip-member", skip_aliases)
+
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+
+# -- Options for HTML output ----------------------------------------------
+
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "navigation_depth": -1,
+}
+
+# Napoleon settings
+napoleon_numpy_docstring = False

docs/index.rst

@@ -0,0 +1,11 @@
+Data Types for NI Python APIs
+=============================
+.. toctree::
+   :maxdepth: 3
+
+   autoapi/index
+
+Indices and tables
+------------------
+* :ref:`modindex`
+* :ref:`search`