Within-Field Docstring Merging about custom_inherit HOT 7 CLOSED

Hi @Zeitsperre thanks for the nice example.

This is certainly feasible - I wrote a merge-style like this a few years ago, and it wasn't all that bad to implement (unfortunately there is no trace of it...). That being said, you could certainly leverage the docstring parsing tools that are included in this library to implement this relatively easily.

Specifically parse_napoleon_doc will give you a dictionary containing all of the sections of the parsed docstring. You can access the Parameters section of this and parse it for the individual parameters within and do a specialized merge for this.

Your use case with a wrapper is an interesting one that I hadn't considered. I would definitely be open to adding this merge-style to the zoo.

from custom_inherit.

Ok sounds pretty cool. I'll see when I have time to work on this but I'll start by forking master and examining the algorithm based off your test examples. What would be good to know going in is how best to handle the order of signature elements (ie: parent args --> child args --> parent kwargs --> child kwargs).

Is there currently a way to link the entries under Parameters to their call signatures to know which is an arg/kwarg?

from custom_inherit.

Presently, is no way to do that. I would be open to making these call-signatures available to the merge styles in version 3.0 after dropping support for Python 2.7.

So that I have more context: in what case would you want to know if an argument is an arg/kwarg, for the purpose of docstring-merging?

from custom_inherit.

I was thinking along the lines of parameter entry order. It would be good to have the signatures to appear in such a way that args appear before kwargs.

On second thought, I could see this getting complicated as args depend on order and if two functions are mixing args in their docstrings, it could give the impression that the function call is set up in that order. To build on the example above, the problem would be how to regulate the order in which the Parameters appear.

Let's suppose that z is an arg of func foo and y is a kwarg. How would one order the following signatures in the docstring?

    Parameters
    ----------
    x : str (child arg)
      some string
    y : str (child kwarg)
      some other string
    z : int (parent arg)
      some number

I feel now that this might be beyond the scope of custom-inherit. Mixing signatures demands kwargs.

from custom_inherit.

Hi all,

I am also very interested in such a option, and I developed three new built-in styles that allow such inner section merging. You can find it on my repo https://github.com/Boubsi/custom_inherit/tree/inner_section_merging.

The new built-in styles are called (for now) "numpy_with_merge", "numpy_napoleon_with_merge" and "google_with_merge".

With those styles, if there is an overlap in some section of child and parents docstrings, the resulting section will be the concatenation of parent's and child's section. It works for all sections except some sections for which it is not relevant to perform the merge (such as "Summary" or "Examples" sections.

For example, here is the docstring I wrote for the "numpy_with_merge" style:

    """
    Behaves identically to the 'numpy' style, but also merges sections that
    overlap, instead of only keeping the child's section. All sections are
    concerned except sections "Short Summary", "Extended Summary", "Deprecation
    Warning" and "Examples" for which the 'numpy' style behaviour applies.

    Example:
        - parent's docstring:

            ''' Parent's line

                Parameters
                ----------
                x: int
                    description of x
                y: Union[None, int]
                    description of y

                Raises
                ------
                NotImplemented Error

                Example
                -------
                >>> parent_func(x=3, y=None)
                NotImplementedError:'''

        - child's docstring:

            ''' Child's line

                Parameters
                ----------
                z: Union[None, int]
                    description of z

                Returns
                -------
                int

                Notes
                -----
                notes blah blah

                Example
                -------
                >>> child_func(x=3, y=None, z=4)
                7'''

        - docstring that is ultimately inherited:

            ''' Child's line

                Parameters
                ----------
                x: int
                    description of x
                y: Union[None, int]
                    description of y
                z: Union[None, int]
                    description of z

                Returns
                -------
                int

                Notes
                -----
                notes blah blah

                Example
                -------
                >>> child_func(x=3, y=None, z=4)
                7'''

What do you think about it? Should I make a merge request on this repo?

from custom_inherit.

@Boubsi this looks like a nice addition to the styles. I think that it would be a convenient add-on for users who want this sort of capability.

A PR would be welcome!

from custom_inherit.

Closed by #31

from custom_inherit.