Metadata-Version: 2.5
Name: sphinx-ai-index
Version: 1.0.0
Summary: Sphinx extension that generates an AI-readable documentation index
Author-email: team useblocks <info@useblocks.com>
Requires-Python: >=3.11,<4
Description-Content-Type: text/markdown
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Typing :: Typed
License-File: LICENSE
Requires-Dist: sphinx>=7.4,<10
Requires-Dist: docutils>=0.21
Project-URL: Changelog, https://github.com/useblocks/sphinx-needs/blob/master/packages/sphinx-ai-index/docs/changelog.rst
Project-URL: Issues, https://github.com/useblocks/sphinx-needs/issues
Project-URL: Repository, https://github.com/useblocks/sphinx-needs
Import-Name: sphinx_ai_index

# 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:

```bash
pip install sphinx-ai-index
```

Or add it to your `pyproject.toml`:

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

## Usage

Add the extension to your Sphinx `conf.py`:

```python
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:

```rst
.. 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:

```json
{
  "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

sphinx-ai-index is developed in the
[sphinx-needs repository](https://github.com/useblocks/sphinx-needs), 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`](https://github.com/useblocks/sphinx-needs/blob/master/AGENTS.md).

