Skip to content

fix: show component docstrings in Sphinx autodoc - #84

Merged
maartenbreddels merged 1 commit into
masterfrom
fix/component-sphinx-autodoc
Nov 10, 2026
Merged

maartenbreddels merged 1 commit into
masterfrom
fix/component-sphinx-autodoc

Conversation

@maartenbreddels

Copy link
Copy Markdown
Contributor

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. ComponentFunction already copies the docstring and signature from the wrapped function, but Sphinx does not treat a ComponentFunction object as a function.

Change

ComponentFunction now 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, and self is still not passed in.

The method makes inspect.isroutine return true for a component. Sphinx uses that check to choose its function and method documenters. A wrapper function with functools.wraps also makes Sphinx work, but the result is no longer a ComponentFunction and it has no .widget() method.

Validation

  • I built a small Sphinx project that uses automodule with @solara.component on 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 in conf.py.
  • The new test test_component_function_is_routine failed before the change and passes now. It also checks that a read from the class and from an instance returns the same component.
  • Solara's tests/unit/autorouting_test.py and tests/unit/website_intersphinx_test.py pass against this branch. One test in them is skipped.

Gaps

Other tools that call inspect.isroutine now also see components as routines. I tested only Sphinx. ComponentWidget, the component type for a widget class, does not change.

Align results

Caution

/align was not run on this change: Maarten approved the exact change in the session after an explanation of what __get__ does.

Crossreview results

Caution

/crossreview was 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

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
maartenbreddels marked this pull request as ready for review November 10, 2026 14:33
@maartenbreddels
maartenbreddels merged commit 2e9e1bc into master Nov 10, 2026
25 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