pdoc
pdoc copied to clipboard
pdoc3
Numpydoc "Methods" section formatting
Expected Behavior
The numpy docstring guide allows for a Methods section where you could list class member functions.
I expect this section to be formatted similar like the Parameters section, i.e. as a list with each function an extra element in this list.
Actual Behavior
The 'Members' heading is formatted in the right way, but the functions are not formatted into a list. They are just merged into a single paragraph.
Steps to Reproduce
class Photo(object):
"""
Array with associated photographic information.
Attributes
----------
exposure : float
Exposure in seconds.
Methods
-------
colorspace(c='rgb')
Represent the photo in the given colorspace.
gamma(n=1.0)
Change the photo's gamma exposure.
"""
def colorspace(self, c='rgb'):
"""Set the colorspace.
"""
self.cs = c
def gamma(self, n=1.0):
"""Set gamma correction.
Parameters
----------
n: float
The gamma correction factor
"""
self.gamma = n
Additional info
- pdoc version: 0.9.1
Indeed, while several kinds of sections are accounted for, Methods is not among them: https://github.com/pdoc3/pdoc/blob/6cfbc4fa0f09de79c51aedb435707a4dcd3b01b9/pdoc/html_helpers.py#L188-L204
Given the variability of the section syntax (methods' default parameters can take form of any valid Python code), this will require a complete new regex, I believe.
The workaround I can think of is to opt for simple markdown and jot a list form:
Methods
-------
* `colorspace(c='rgb')` -
Represent the photo in the given colorspace.
* ...
Note, to force a line break instead of dash separator, you need to end the line with <br> or two spaces. Not too clean. :confused:
TBH, with methods listed in the index and documented further below, the section does feel somewhat redundant.
- pdoc version: pip and git clone
This only tells something at the moment. But in a short while, the only fixed reference one can use will be the original post date, requiring of one to look up the version history of the time ...
For brief member function descriptions an explicit methods section is indeed redundant. But if the method functions's docstrings are very long with long parameter descriptions and nice example codes, then a concise methods section with a meaningful order of functions and a brief description of each function can be quite useful. Since it is listed in the numpy docstring guide the user should decide whether to use it or not.
Anyways, a quick solution would be to add the methods section along with 'Returns' and 'Raises' to line 192
https://github.com/pdoc3/pdoc/blob/6cfbc4fa0f09de79c51aedb435707a4dcd3b01b9/pdoc/html_helpers.py#L188-L204
this produces somewhat ok results in the html output. But it could be improved by making the function names links to the full descriptions. You would get links by marking the functions as inline code and qualify them by the class name:
Methods
-------
`Photo. colorspace`(c='rgb')
Represent the photo in the given colorspace.
`Photo.gamma`(n=1.0)
Change the photo's gamma exposure.
Not perfect either, see issue #188 .
Seems you are right, support for methods sections needs an extra regexp. Maybe I manage to look into this.
No, unfortunately not. I did not find time to wrap my head around these regexps.