search

pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.14k stars 146 forks source link

Docstrings under `Parameters` are mangled #388

Closed ethanabrooks closed 2 years ago

ethanabrooks commented 2 years ago

Expected Behavior

Something like this:

image

Actual Behavior

image

Steps to Reproduce

Documentation is based on the following python file:

def command():
    """
    Parameters
    ----------
    >>> command()
    usage: help string
    """
    pass

The issue seems to arise from putting docstring examples (i.e. example code marked by >>> with expected output) under the numpydoc Parameters marker.

To generate the docs I am using 

pdoc3 --html --force file.py

Additional info

kernc commented 2 years ago

Parameters in numpydoc is a reserved heading that ordinarily leads the list of function parameters, which are recognized and transformed by a regex. Apparently, usage: line matches. This goes for the whole section. https://github.com/pdoc3/pdoc/blob/2cce30a9b55eeeddc1ed826c8a2ada53777c3eea/pdoc/html_helpers.py#L201-L207 You could rename the heading, or indent the doctest into a parameter definition to act as verbatim example code block. If the function takes no parameters, best remove the section.

ethanabrooks commented 2 years ago

Hi, yes it seems that it is not possible to do what I want to do in either pdoc3 or sphinx. I actually ended up just breaking out a separate Examples section which seems to be the numpydoc way of doing this kind of thing.