Failure to parse docstrings where a section contains header-like content
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
numpydoc.docscrape.NumpyDocString in version 1.9.0 fails to parse docstrings if there is content within a section that resembles a section header, e.g. the "Parameters\n----------" contains " Parameters\n----------"
Example reproducer: a function that takes a function as an argument and returnsanother function. The following docstring explains the returned function:
def wrapper(func):
'''
Wrap a simple function so that it takes a message string that gets printed to stdout when invoked.
Parameters
----------
func: function
Function to be wrapped. This can be any arbitrary synchronous function.
Returns
-------
wrapped_function: function
The returned function has the following signature::
wrapped_function(
message,
*args,
*kwargs,
)
\'\'\'
Parameters
----------
message: str
A custom message to be printed when the wrapped function is called.
*args
Additional arguments that are passed into the original function.
**kwargs
Extra arguments to the original function.
\'\'\'
'''
However, when using numpydoc.docscrape.NumpyDocString to parse this docstring, for example:
parsed = NumpyDocString(<example docstring above>)
...an exception is raised claiming to have duplicate Parameters section:
ValueError: The section `Parameters` appears twice in
Wrap a simple function so that it takes a message string that gets printed to stdout when invoked.
The desired behavior is to treat the nested Parameters "section" as regular content and not an actual section.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the NumpyDocString entry point and run the provided wrapper docstring reproducer against version 1.9.0. Trace how indented header-like content is recognized while parsing sections, then add coverage showing that the nested Parameters text remains regular content and does not raise a duplicate-section error.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100