sphinx-ai-index

A Sphinx extension that generates an AI-readable documentation index (ai_docs_index.json) in the HTML output directory on every build.

Installation

Install from PyPI:

pip install sphinx-ai-index

Or add it to your pyproject.toml:

dependencies = [
    "sphinx-ai-index",
]

Usage

Add the extension to your Sphinx conf.py:

extensions = ["sphinx_ai_index"]

That's it. On the next HTML build, ai_docs_index.json will appear in the output directory.

.. page-summary:: directive

Optionally annotate any RST page with a short prose description:

.. page-summary::

    This page covers the installation of the package on all major platforms,
    including system requirements and VS Code extension setup.

Pages without the directive are still indexed; their summary field will be an empty string.

Output format

ai_docs_index.json is written to the HTML output directory:

{
  "version": "1.0",
  "pages": [
    {
      "rst_source_path": "_sources/basics/installation.rst.txt",
      "html_path": "basics/installation.html",
      "title": "Installation",
      "sections": ["System Requirements", "Installing via pip"],
      "summary": "Covers installation on all platforms."
    }
  ]
}

Development

sphinx-ai-index is developed in the sphinx-needs repository, as packages/sphinx-ai-index, alongside the extensions whose documentation builds use it. The commands -- uv run poe test-ai-index for the test suite, the lint and type-check tasks, the release recipe -- are in that repository's root AGENTS.md.