Skip to content

Sphinx Site

The framework integrates a Sphinx HTML site alongside the hand-written KB artifacts (cards, math docs). The Sphinx site provides auto-generated, always-up-to-date API documentation for Python projects.

Note

This page covers Sphinx (Python). For Doxygen-based C/C++ documentation, see Doxygen Site.

Why Both Cards and Sphinx?

Artifact Provides Maintained by
KB Card Why --- design rationale, algorithm, failure modes, engineering notes kb-developer (manual)
Sphinx docstrings What --- function purpose, parameters, return values, exceptions kb-developer (manual)
Sphinx HTML site How it connects --- API reference, class hierarchies, source browser, optional call graphs Auto-generated from source

Cards tell you why a function exists and how the algorithm works. The Sphinx site tells you what the public API looks like, how classes relate, and where to find the source --- structural information that changes with every refactor and is impractical to track manually.

What the Sphinx Site Generates

  • API reference --- autodoc-generated pages for every module with docstrings
  • Class hierarchies --- inheritance trees with cross-references
  • Source browser --- annotated source with hyperlinked symbols (via viewcode)
  • Type cross-references --- :type: directives link to class/module docs
  • Search --- full-text search across all documented symbols
  • Call graphs (optional) --- via graphviz extension or third-party tools

Setup

Prerequisites

Installation

  1. Copy the conf.py template during framework installation:

    cp scripts/sphinx-conf.py YOUR_PROJECT/docs/conf.py

  2. Edit docs/conf.py --- set project, adjust sys.path.insert for your source directory layout.

  3. Create the API documentation scaffold:

    mkdir -p docs/api
# For each top-level module:
sphinx-apidoc -o docs/api/ src/mypackage/ --separate

  4. Create docs/index.rst:

    My Project
==========

.. toctree::
   :maxdepth: 2

   api/modules

  5. Configure project-config.md:

    docs_tool: "sphinx"
sphinx_enabled: true
sphinx_config: "docs/conf.py"
sphinx_build_cmd: "sphinx-build -b html docs/ docs/_build/html/"
sphinx_output_dir: "doc/sphinx/"
sphinx_url: ""

  6. Add to .gitignore (HTML output is generated, not committed):

    docs/_build/

Building

sphinx-build -b html docs/ docs/_build/html/
# Output: docs/_build/html/index.html

Rebuild after any source change that affects function signatures, module structure, or class hierarchies.

INDEX Linking

The KB INDEX includes a Sphinx column that links each source file to its auto-generated HTML page:

| ID  | File              | Card                | Sphinx                                           |
|-----|-------------------|---------------------|--------------------------------------------------|
| S01 | src/solve.py      | [S01](cards/S01.md) | [docs](../sphinx/_build/html/api/mypackage.solve.html)  |
| N02 | src/numeric.py    | [N02](cards/N02.md) | [docs](../sphinx/_build/html/api/mypackage.numeric.html)|
| A03 | src/analyze.py    | ---                 | [docs](../sphinx/_build/html/api/mypackage.analyze.html)|

Agents looking up a card can follow the Sphinx link to see the auto-generated API reference, complementing the card's hand-written content.

URL Pattern

Sphinx uses module dotted paths for HTML output (simpler than Doxygen's _8 filename mangling):

Source path HTML filename
src/mypackage/solve.py api/mypackage.solve.html
src/mypackage/io/reader.py api/mypackage.io.reader.html
src/mypackage/__init__.py api/mypackage.html

The pattern: take the Python module dotted path, prepend api/, append .html.

Scoring

The API documentation quality gate (8 points max) includes:

Gate Points Pass condition
Coverage 3 Every public function/method has a docstring
Parameters 2 Every param has :param: and :type:
Cross-refs 1 .. seealso:: links include card IDs
Site generated 1 HTML output exists and is not stale
Call graphs 1 Call graph artifacts exist (manual graphviz or third-party)

Consistency Checks

The kb-reviewer verifies:

  • INDEX Sphinx links resolve to existing HTML files
  • Card Call Graph section is consistent with actual call relationships in source
  • Sphinx site is not stale (source modified after last build -> STALE)

Optional: Hosting on GitHub Pages

Projects can publish the Sphinx site alongside other documentation using a GitHub Actions workflow:

- name: Install Sphinx
  run: pip install sphinx
- name: Install Graphviz
  run: sudo apt-get install -y graphviz
- name: Build Sphinx
  run: sphinx-build -b html docs/ docs/_build/html/
- name: Deploy
  uses: actions/upload-pages-artifact@v3
  with:
    path: docs/_build/html