Repository navigation
docs: publish an intersphinx inventory - #85
Merged
Merged
Conversation
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
marked this pull request as ready for review
November 10, 2026 15:33
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an
objects.invfile 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.invfile, 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 asuse_refand its inventory cannot point to another website.Change
hooks/objects_inv.pyis a mkdocs hook. On each docs build, it reads the#### nameheadings indocs/api.mdand writesobjects.invto the site. Each of the 11 functions is listed asreacton.nameandreacton.core.name, with a link to its heading.docs/api.mdshows the setup and an example.Users configure it like this, because the file is at the default intersphinx location:
Validation
mkdocs buildwith this branch. It wroteobjects.inv, andapi/index.htmlhas all 11 heading ids that the inventory links to.nitpicky = Trueagainst that file. All 5 references resolved to the expected URLs with no warnings, for example:func:reacton.use_state`` tohttps://reacton.solara.dev/en/latest/api/#use_state.Gaps
docs/api.md. It does not list the widget wrappers inreacton.ipywidgetsandreacton.ipyvuetify.Align results
Caution
/alignwas not run on this change: Maarten asked for the Reacton docs directly in the session.Crossreview results
Caution
/crossreviewwas not run on this change: a mistake affects only doc links, and a real Sphinx build checked the output.🤖 Generated with Claude Code