blank lines between parameters

[lukashergt]

Does docrep require the parameters in the docstring to be written without a blank line separating them? It seems like a blank line is taken as the end of the parameter section.

Would it be possible to allow blank lines such that the raw docs look a little neater?

[Chilipp]

Hi Lukas! Thanks for your report :) Yes, this might cause a problem since the Parameters are in the param_like_sections attribute. Could you give a small example? I suspect you could simply change this behaviour by subclassing the DocstringProcessor and putting the 'Parameters' in the text_sections attribute:

class DocstringProcessorWithBlanks(DocstringProcessor):

    param_like_sections = [s for s in DocstringProcessor.param_like_sections 
                           if s != 'Parameters']

    text_sections = ['Parameters'] + DocstringProcessor.text_sections

Or simply put all param_like_sections into the text_sections:

class DocstringProcessorWithBlanks(DocstringProcessor):

    param_like_sections = []

    text_sections = DocstringProcessor.text_sections + \
        DocstringProcessor.param_like_sections

[lukashergt]

Thanks for the quick reply, Philipp!

Haha, sorry should have directly tried to strip it down, then my question would have been more specific...

So, as it turns out for simple functions blank lines are fine. However, in class methods blank lines don't work.

Example just with functions

Code

import docrep

docstrings = docrep.DocstringProcessor()

@docstrings.get_sectionsf('do_something')
@docstrings.dedent
def do_something(a, b):
    """
    Add two numbers

    Parameters
    ----------
    a: int
        The first number

    b: int
        The second number

    Returns
    -------
    int
        `a` + `b`"""
    return a + b

@docstrings.dedent
def do_more(c, *args, **kwargs):
    """
    Add two numbers and multiply it by c

    Parameters
    ----------
    c: int
        multiplication parameter

    %(do_something.parameters)s

    Returns
    -------
    int
        (`a` + `b`) * c"""
    return do_something(*args, **kwargs) * c

print(do_more.__doc__)

Output as desired

Add two numbers and multiply it by c

Parameters
----------
c: int
    multiplication parameter

a: int
    The first number

b: int
    The second number

Returns
-------
int
    (`a` + `b`) * c

Example using a class and method docstrings

Code

import docrep

docstrings = docrep.DocstringProcessor()

class A:
    @docstrings.get_sectionsf('do_something')
    @docstrings.dedent
    def do_something(a, b):
        """
        Add two numbers

        Parameters
        ----------
        a: int
            The first number

        b: int
            The second number

        Returns
        -------
        int
            `a` + `b`"""
        return a + b

    @docstrings.dedent
    def do_more(c, *args, **kwargs):
        """
        Add two numbers and multiply it by c

        Parameters
        ----------
        c: int
            multiplication parameter

        %(do_something.parameters)s

        Returns
        -------
        int
            (`a` + `b`) * c"""
        return do_something(*args, **kwargs) * c

a = A

print(a.do_more.__doc__)

Output: parameter b missing in printed docstring

Add two numbers and multiply it by c

Parameters
----------
c: int
    multiplication parameter

a: int
    The first number

Returns
-------
int
    (`a` + `b`) * c

[lukashergt]

Both of your suggestions seem to work. Thanks, Philipp, that way I can keep my blank lines.

[Chilipp]

Both of your suggestions seem to work.

Great 😄

So, as it turns out for simple functions blank lines are fine. However, in class methods blank lines don't work.

This is weird because actually the DocstringProcessor does not care whether it is a method or a function. I'll have a look into it and until then, we should keep this issue open.

---

As a little comment: the sections in the text_sections attribute assume that they end either by the next section or the end of the docstring. Therefore something like

def func(a=1):
    """
    An awesome function

    Parameters
    ----------
    a: int
        A parameter

    And here we have a paragraph that has nothing to 
    do with the Parameters section
    """

will cause problems if you have the 'Parameters' in the text_sections attribute.

[lukashergt]

sections in the text_sections attribute assume that they end either by the next section or the end of the docstring

Good to know, I'll look out for that, but I guess typically this won't be an issue as the parameters section usually is followed by the results section.

[jgostick]

FYI: I am currently using this 'bug' as a feature. If I want to stop certain parameters from being inherited by subclasses I but them after a line break. This way I can re-define those specific parameters in subclasses without having duplicates (or without having the deal with removing them from the docrep dict).

This pertains to the feature request I just posted (issue #16)