Repository navigation
fix: show component docstrings in Sphinx autodoc - #84
Merged
Merged
Conversation
Sphinx users could not document their components. Sphinx autodoc skips a module-level component without a warning, and it shows a component on a class as "Method = react.component(mylib.Method)". The docstring was on the object, but Sphinx did not treat the object as a function. ComponentFunction now has a __get__ method that returns the component itself. Python already gave that result, so attribute access does not change. The method makes inspect.isroutine true, and Sphinx uses that check to choose its function documenter. A Sphinx build with automodule showed a module-level component and a component on a class with their signatures and docstrings. A new test failed before this change and passes now. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
maartenbreddels
marked this pull request as ready for review
November 10, 2026 14: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.
Sphinx autodoc now documents components as functions and methods, so authors can publish the docstrings of their components.
Problem
Libraries that use Reacton or Solara components and document their code with Sphinx lose those components in their API reference. Sphinx autodoc skips a module-level component without a warning. It shows a component on a class only as
Method = react.component(mylib.Method), without the docstring.ComponentFunctionalready copies the docstring and signature from the wrapped function, but Sphinx does not treat aComponentFunctionobject as a function.Change
ComponentFunctionnow has a__get__method that returns the component itself. Python already gives that result for an attribute without__get__, so reading a component from a class or an instance does not change, andselfis still not passed in.The method makes
inspect.isroutinereturn true for a component. Sphinx uses that check to choose its function and method documenters. A wrapper function withfunctools.wrapsalso makes Sphinx work, but the result is no longer aComponentFunctionand it has no.widget()method.Validation
automodulewith@solara.componenton a module-level function and on a method. Before this change, the first was missing and the second had no docstring. With this change, both show their signature and docstring, without a patch inconf.py.test_component_function_is_routinefailed before the change and passes now. It also checks that a read from the class and from an instance returns the same component.tests/unit/autorouting_test.pyandtests/unit/website_intersphinx_test.pypass against this branch. One test in them is skipped.Gaps
Other tools that call
inspect.isroutinenow also see components as routines. I tested only Sphinx.ComponentWidget, the component type for a widget class, does not change.Align results
Caution
/alignwas not run on this change: Maarten approved the exact change in the session after an explanation of what__get__does.Crossreview results
Caution
/crossreviewwas not run on this change: the change is one method that returns its own object, and a new test and a real Sphinx build check it.🤖 Generated with Claude Code