Documentation Index
Fetch the complete documentation index at: https://demo.agenticlabs.com/llms.txt
Use this file to discover all available pages before exploring further.
High-level description
This code provides a Sphinx extension that customizes the parsing of the “Returns” section in NumPy-style docstrings. It specifically formats the return values to include hyperlinks to their types using the :class: role.
References
This code references the NumpyDocstring class from the sphinx.ext.napoleon module.
Symbols
process_return
Description
This function iterates through a list of lines (presumably from a docstring’s “Returns” section) and reformats lines that match a specific pattern.
| Name | Type | Description |
|---|
| lines | list[str] | A list of strings representing lines in a docstring’s “Returns” section. |
Outputs
| Name | Type | Description |
|---|
| generator[str] | Yields reformatted lines or the original line if no match is found. |
Internal Logic
- Iterates through each line in the input
lines.
- Attempts to match the line with the regular expression
r"(?P<param>\w+)\s+:\s+(?P<type>[\w.]+)". This pattern captures a “parameter” and its “type” separated by a colon.
- If a match is found:
- It reformats the line to
f'-{m["param"]} (:class:~)', which creates a hyperlink for the type using the :class: role.
- If no match is found, it yields the original line.
scanpy_parse_returns_section
Description
This function overrides the _parse_returns_section method of the NumpyDocstring class. It processes the “Returns” section of a docstring to format return values with hyperlinks to their types.
| Name | Type | Description |
|---|
| self | NumpyDocstring | The NumpyDocstring instance. |
| section | str | The content of the “Returns” section from the docstring. |
Outputs
| Name | Type | Description |
|---|
| list[str] | Returns a list of strings representing the formatted “Returns” section. |
Internal Logic
- Calls
process_return to reformat the lines of the “Returns” section.
- Formats the processed lines using
_format_block with “:returns: ” as the prefix.
- Appends an empty line if the formatted lines are not empty.
- Returns the formatted lines.
setup
Description
This function is the entry point for the Sphinx extension. It modifies the behavior of the NumpyDocstring class to use the custom scanpy_parse_returns_section method.
| Name | Type | Description |
|---|
| app | Sphinx | The Sphinx application object. |
Internal Logic
Sets the _parse_returns_section attribute of the NumpyDocstring class to the custom scanpy_parse_returns_section function.
Dependencies
| Dependency | Purpose |
|---|
| sphinx | Used for interacting with Sphinx and its components. |
| sphinx.ext.napoleon | Used for parsing NumPy-style docstrings. |
| re | Used for regular expression matching. |
TODOs
# code from https://github.com/theislab/scanpy/blob/master/docs/extensions/typed_returns.py
# with some minor adjustment
