Numpydoc "Methods" section formatting

[janscience]

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

[kernc]

Indeed, while several kinds of sections are accounted for, Methods is not among them:

pdoc/pdoc/html_helpers.py

Lines 188 to 204 in 6cfbc4f

	if section == 'See Also':
	body = re.sub(r'\n\s{4}\s*', ' ', body) # Handle line continuation
	body = re.sub(r'^((?:\n?[\w.]* ?: .*)+)|(.*\w.*)',
	_ToMarkdown._numpy_seealso, body)
	elif section in ('Returns', 'Yields', 'Raises', 'Warns'):
	body = re.sub(r'^(?:(?P<name>\*{0,2}\w+(?:, \*{0,2}\w+)*)'
	r'(?: ?: (?P<type>.*))|'
	r'(?P<just_type>\w[^\n`*]*))(?<!\.)$'
	r'(?P<desc>(?:\n(?: {4}.*|$))*)',
	_ToMarkdown._numpy_params, body, flags=re.MULTILINE)
	elif section in ('Parameters', 'Receives', 'Other Parameters',
	'Arguments', 'Args', 'Attributes'):
	name = r'(?:\w|\{\w+(?:,\w+)+\})+' # Support curly brace expansion
	body = re.sub(r'^(?P<name>\*{0,2}' + name + r'(?:, \*{0,2}' + name + r')*)'
	r'(?: ?: (?P<type>.*))?(?<!\.)$'
	r'(?P<desc>(?:\n(?: {4}.*|$))*)',
	_ToMarkdown._numpy_params, body, flags=re.MULTILINE)

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. 😕

TBH, with methods listed in the index and documented further below, the section does feel somewhat redundant.

[kernc]

• 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 ...

[janscience]

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

pdoc/pdoc/html_helpers.py

Lines 188 to 204 in 6cfbc4f

	if section == 'See Also':
	body = re.sub(r'\n\s{4}\s*', ' ', body) # Handle line continuation
	body = re.sub(r'^((?:\n?[\w.]* ?: .*)+)|(.*\w.*)',
	_ToMarkdown._numpy_seealso, body)
	elif section in ('Returns', 'Yields', 'Raises', 'Warns'):
	body = re.sub(r'^(?:(?P<name>\*{0,2}\w+(?:, \*{0,2}\w+)*)'
	r'(?: ?: (?P<type>.*))|'
	r'(?P<just_type>\w[^\n`*]*))(?<!\.)$'
	r'(?P<desc>(?:\n(?: {4}.*|$))*)',
	_ToMarkdown._numpy_params, body, flags=re.MULTILINE)
	elif section in ('Parameters', 'Receives', 'Other Parameters',
	'Arguments', 'Args', 'Attributes'):
	name = r'(?:\w|\{\w+(?:,\w+)+\})+' # Support curly brace expansion
	body = re.sub(r'^(?P<name>\*{0,2}' + name + r'(?:, \*{0,2}' + name + r')*)'
	r'(?: ?: (?P<type>.*))?(?<!\.)$'
	r'(?P<desc>(?:\n(?: {4}.*|$))*)',
	_ToMarkdown._numpy_params, body, flags=re.MULTILINE)

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.

[hombit]

Excuse me, is there any progress here?

[janscience]

No, unfortunately not. I did not find time to wrap my head around these regexps.

[hombit]

Thank you for the answer!