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."
    }
  ]
}

Field	Description
rst_source_path	Path to the RST source in the HTML output (under _sources/)
html_path	Path to the rendered HTML page, relative to the output root
title	Page title
sections	Titles of the top-level subsections within the page
summary	Text from the .. page-summary:: directive, or ""

Development

git clone https://github.com/useblocks/sphinx-ai-index.git
cd sphinx-ai-index
rye sync
rye run tox

See CONTRIBUTING.md for more details.