Sphinx Lens

Structure-aware indexing and precise navigation for Sphinx documentation.

Sphinx knows things about your documentation that nothing downstream gets to use: which text belongs to which section, that django.db.transaction.atomic is a documented object with a canonical name, and where every cross-reference points. Then it renders HTML and throws that away.

Sphinx Lens is a Sphinx builder that writes it down instead. The output is a single JSON index of documents, sections, and domain objects, each with a stable reference and its own scoped text, plus the compiled link graph between them. Coding agents get to read one precise scope instead of grepping a source tree.

Quick start

Install Sphinx Lens in the same environment as your documentation and build the index like any other Sphinx artifact:

sphinx-build -b lens docs/ docs/_build/lens/
sphinx-lens locate "connection timeout" --index docs/_build/lens/
sphinx-lens inspect py:class:example.Client --index docs/_build/lens/
sphinx-lens read guide/network#timeouts --index docs/_build/lens/
sphinx-lens links guide/network#timeouts --index docs/_build/lens/

The lens builder is discovered through Sphinx's builder entry point; no conf.py change is required. It loads the project's formats, extensions, and domains, then writes docs/_build/lens/index.json. Projects can expose this as make lens; sphinx-lens build docs/ is the equivalent convenience command.

Sphinx executes conf.py during every build. Only index projects you trust, and run the command in the project's documentation environment so MyST, autodoc, themes, and project-specific extensions are importable.

Install the bundled agent skill with Library Skills:

uvx library-skills install --skill sphinx-lens --yes

locate is lexical. It finds the right reference so that read and links can do the real work; embedding similarity is out of scope.

Full documentation is at https://mgaitan.github.io/sphinx-lens/. Start with Getting started, or read How it works for why this is a separate artifact rather than a reuse of objects.inv, searchindex.js, or Sphinx doctrees.

Development

• Install dependencies with uv sync.
• New dependency releases are delayed by one week via uv cooldown ([tool.uv].exclude-newer = "1 week"), with per-package overrides when required (for example, ty).
• Make targets and GitHub Actions enable uv's malware check against known malicious-package advisories.
• Install prek as an external tool:

uv tool install prek

• Install git hooks with prek:

prek install

• Run the local QA bundle with prek:

prek run --all-files

• PRs with documentation changes publish a docs preview at:

https://mgaitan.github.io/sphinx-lens/_preview/pr-<PR_NUMBER>/

• Build this project's own index with make lens, and the docs with make docs.