numpy / numpy/numpydoc

Failure to parse docstrings where a section contains header-like content

Open
#640 1 comment 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.