Skip to content

docs: publish an intersphinx inventory - #85

Merged
maartenbreddels merged 1 commit into
masterfrom
feat/intersphinx-objects-inv
Nov 10, 2026
Merged

maartenbreddels merged 1 commit into
masterfrom
feat/intersphinx-objects-inv

Conversation

@maartenbreddels

Copy link
Copy Markdown
Contributor

Adds an objects.inv file to the Reacton docs, so Sphinx projects can link to the Reacton API with intersphinx.

Problem

Projects that document their code with Sphinx use intersphinx to link to the docs of the libraries they use. Intersphinx needs an objects.inv file, which lists each Python object and the URL of its docs. The Reacton docs are built with mkdocs, so they have no such file. Authors must type the URLs by hand. This also affects Solara users, because Solara re-exports Reacton names such as use_ref and its inventory cannot point to another website.

Change

  • hooks/objects_inv.py is a mkdocs hook. On each docs build, it reads the #### name headings in docs/api.md and writes objects.inv to the site. Each of the 11 functions is listed as reacton.name and reacton.core.name, with a link to its heading.
  • The hook raises an error if it finds no headings, so a format change cannot publish an empty inventory.
  • A new section in docs/api.md shows the setup and an example.

Users configure it like this, because the file is at the default intersphinx location:

intersphinx_mapping = {
    "reacton": ("https://reacton.solara.dev/en/latest/", None),
}

Validation

  • I ran mkdocs build with this branch. It wrote objects.inv, and api/index.html has all 11 heading ids that the inventory links to.
  • I built a small Sphinx project with nitpicky = True against that file. All 5 references resolved to the expected URLs with no warnings, for example :func:reacton.use_state`` to https://reacton.solara.dev/en/latest/api/#use_state.

Gaps

  • The inventory lists only the functions with a heading in docs/api.md. It does not list the widget wrappers in reacton.ipywidgets and reacton.ipyvuetify.
  • No automated test covers the hook. A docs build runs it, and a failure in the hook fails that build.

Align results

Caution

/align was not run on this change: Maarten asked for the Reacton docs directly in the session.

Crossreview results

Caution

/crossreview was not run on this change: a mistake affects only doc links, and a real Sphinx build checked the output.

🤖 Generated with Claude Code

Sphinx projects could not link to the Reacton API docs, because the
site has no objects.inv file. Authors had to write the URLs by hand.

A mkdocs hook now writes the file on each docs build, from the
headings in docs/api.md. The file therefore cannot get out of date,
and no generated binary goes into git. Read the Docs serves it at the
default intersphinx location, so users do not need a custom URL.

A mkdocs build wrote the file, and a Sphinx build with nitpicky = True
resolved 5 references to the correct anchors with no warnings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@maartenbreddels
maartenbreddels marked this pull request as ready for review November 10, 2026 15:33
@maartenbreddels
maartenbreddels merged commit 2816665 into master Nov 10, 2026
24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant