Module: vemomoto_core.tools.doc_utils

This module provides decorators and a superclass that allow methods to “inherit” documentation from other given methods or similar methods from super classes when a documentation is generated via Shinx.

Usage

If documentation shall be ‘inherited’ from super classes, the base class must inherit from the meta-class DocMetaSuperclass. Otherwise, the source of the documentation must be specified via the inherit_doc() decorator.

• Documentation of single arguments (numpy format) is taken from the super method if not provided for the child.

• You may add a new description of the method and renew the documentation of arguments to your liking, but undocumented arguments will be documented from the super class.

• Documentation can be replaced, inserted, added, or ignored.

• The particular procedure can be controlled by adding a marker string to the beginning of the header, footer, type, or argument description.

• Description starting with # will be overwritten by the super method.

• Description starting with <! will be put before the description from the super method.

• Description starting with !> will be put behind the description from the super method.

• Description without starting marker will replace the description from the super method.

• Super methods can have documentation that is not carried over to the children.

• Lines after a line starting with ~+~ will be ignored by inheriting functions.

• The tool is applicable to both entire classes (via metaclasses) and single methods (via decorators). The two can be combined.

• Via the decorator, multiple methods can be screened for suitable parameter definitions.

• This is useful if the methods of concern bundles many other methods.

Example 1: Inheriting documentation from the super class

from vemomoto_core.tools.doc_utils import DocMetaSuperclass, inherit_doc

class BaseClass(metaclass=DocMetaSuperclass)
    def mymethod(myargument):
        """This does something

        ~+~

        This text will not be seen by the inheriting classes

        Parameters
        ----------
        myargument : int
            Description of the argument

        """
        [...]

    @inherit_doc(mymethod)
    def mymethod2(myargument, otherArgument):
        """>!This description is added to the description of mymethod
        (ignoring the section below ``~+~``)

        Parameters
        ----------
        otherArgument : int
            Description of the other argument
        [here the description of ``myargument`` will be inserted from mymethod]

        """
        BaseClass.mymethod(myargument)
        [...]


class MyClass1(BaseClass):
    def mymethod2(myargument):
        """This overwirtes the description of ``BaseClass.mymethod``

        [here the description of ``myargument`` from BaseClass.mymethod2 is inserted
         (which in turn comes from BaseClass.mymethod); otherArgument is ignored]
        """

        BaseClass.mymethod(myargument)
        [...]

class MyClass2(BaseClass):
    def mymethod2(myargument, otherArgument):
        """#This description will be overwritten

        Parameters
        ----------
        myargument : string <- this changes the type description only
        otherArgument [here the type description from BaseClass will be inserted]
            <! This text will be put before the argument description from BaseClass
        """

        BaseClass.mymethod2(myargument, otherArgument)
        [...]

Example 2: Inheriting documentation from an other method

from vemomoto_core.tools.doc_utils import inherit_doc

def method1(arg1):
    """This does something

    Parameters
    ----------
    arg1 : type
        Description

    """
    [...]

def method2(arg2):
    """This does something

    Parameters
    ----------
    arg2 : type
        Description

    """
    [...]

def method3(arg3):
    """This does something

    Parameters
    ----------
    arg3 : type
        Description

    """
    [...]

@inherit_doc(method1, method2, method3)
def bundle_method(arg1, arg2, arg3):
    """This does something

    [here the parameter descriptions from the other
     methods will be inserted]

    """
    [...]

Classes:

DocMetaSuperclass(classname, bases, cls_dict)

Meta-class providing the opportunity to inherit documentation from super classes.

Functions:

add_parent_doc(child, parent)
adjust_indent(string, difference)
get_indent(string)
get_indent_multi(string)
inherit_doc(*fromfuncs)	Decorator: Copy elements from the docstrings of the fromfuncs wherever the documentation of the decorated method is not given.
merge(child_str, parent_str[, indent_diff, ...])
should_append(string)
should_ignore(string)
should_insert(string)
split_variables_numpy(docstr[, stripPrivate])
staticmethod_inherit_doc(*fromfuncs)	Decorator: Declare the decorated method as a static method and copy elements from the docstrings of the fromfuncs wherever the documentation of the decorated method is not given.
strip_lines(string)
strip_private(string)

class DocMetaSuperclass(classname, bases, cls_dict)

Bases: type

Meta-class providing the opportunity to inherit documentation from super classes.

add_parent_doc(child, parent)

adjust_indent(string: str, difference: int) → str

get_indent(string: str) → int

get_indent_multi(string: str) → int

inherit_doc(*fromfuncs)

Decorator: Copy elements from the docstrings of the fromfuncs wherever the documentation of the decorated method is not given.

merge(child_str, parent_str, indent_diff=0, joinstr='\n')

should_append(string)

should_ignore(string)

should_insert(string)

split_variables_numpy(docstr: str, stripPrivate: bool = False)

staticmethod_inherit_doc(*fromfuncs)

Decorator: Declare the decorated method as a static method and copy elements from the docstrings of the fromfuncs wherever the documentation of the decorated method is not given.

strip_lines(string)

strip_private(string: str)