pdoc3 / pdoc3/pdoc

Numpydoc "Methods" section formatting

Open
#256 6 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
1.2k
Forks
146
PR merge metrics
No merged PRs in 30d

Description

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

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

No file or test is named. Reproduce the issue with the supplied Photo class and inspect how pdoc3 parses and renders Numpydoc Methods sections; done means each listed function is rendered as a separate list item, like entries in Parameters.

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
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.