11  Documents

aka majordome_utilities.documents

NoteSignatureEntry 
SignatureEntry(
    fn : type,
    *,
    greedy : bool = True
    ) -> None:

Builds the representation of a function signature.

Parameters 
fn : type
    
The function to build the signature for. 
greedy : bool = True
    
Whether to raise errors for missing docstrings or parameters.
Notedocumentation 
documentation(
    self : Any,
    **kwargs : Any
    ) -> None:

Generates the markdown documentation for the function.

Parameters 
title : str = None
    
The title to use for the section header and callout. By default, the function name is used.

11.1 Tutorial

class Dummy:
    """ A dummy class for testing purposes. """
    def method(self, a, b):
        """ This is a method.

        Parameters
        ----------
        a : int
            This is the first parameter.
        b : int
            This is the second parameter.
        """
        pass

    @staticmethod
    def static_method(a, b):
        """ This is a static method.

        Parameters
        ----------
        a : int
            This is the first parameter.
        b : int
            This is the second parameter.
        """
        pass

    @classmethod
    def class_method(cls, a, b):
        """ This is a class method.

        Parameters
        ----------
        a : int
            This is the first parameter.
        b : int
            This is the second parameter.
        """
        pass

    @property
    def prop(self) -> int:
        """ This is a property. """
        return 42

Documentation of all members at once is discouraged, but it is possible to do so by calling all methods of `DocumentedClass:

doc = DocumentedClass(Dummy)
doc.constructor()
doc.members()
doc.properties()
doc.classmethods()
doc.staticmethods()

For generating more organized documentation, it is possible to selectively include or exclude static methods, class methods and properties. This allows to generate separate sections for each type of member, which can be more readable and easier to navigate.

The constructor:

NoteDummy 
Dummy():

A dummy class for testing purposes.

Only normal methods:

Notemethod 
method(
    self : Any,
    a : Any,
    b : Any
    ):

This is a method.

Parameters 
a : Any
    
This is the first parameter. 
b : Any
    
This is the second parameter.

Only static methods:

Notestatic_method 
static_method(
    a : Any,
    b : Any
    ):

This is a static method.

Parameters 
a : Any
    
This is the first parameter. 
b : Any
    
This is the second parameter.

Only class methods:

Noteclass_method 
class_method(
    cls : Any,
    a : Any,
    b : Any
    ):

This is a class method.

Parameters 
a : Any
    
This is the first parameter. 
b : Any
    
This is the second parameter.

Only properties:

Noteprop 
prop(self : Any): -> int:

This is a property.

11.2 Examples

A minimal function with no parameters and no docstring:

def awesome_useless():
    pass
Noteawesome_useless 
awesome_useless():

(missing summary)

A function with variadic parameters and no documented parameters:

def awesome_useless(*args, **kwargs):
    """ Some useless function. """
    pass
Noteawesome_useless 
awesome_useless(
    *args : Any,
    **kwargs : Any
    ):

Some useless function.

Parameters 
*args : Any
    
(missing description)

A function with variadic parameters with type annotation and explictly documented keyword parameter:

def awesome_useless(*args: tuple[int, ...], **kwargs):
    """ Some useless function.

    Parameters
    ----------
    args : tuple
        Positional arguments. This is intended to be a catch-all for
        any number of positional arguments. Let's write a long text.
    some_kwarg : int = 1
        Keyword argument. This is intended to be a catch-all for any
        number of keyword arguments. Let's write a long text.
    """
    pass
Noteawesome_useless 
awesome_useless(
    *args : tuple[int, ...],
    **kwargs : Any
    ):

Some useless function.

Parameters 
*args : tuple[int, ...]
    
Positional arguments. This is intended to be a catch-all for any number of positional arguments. Let’s write a long text. 
some_kwarg : int  = '1'
    
Keyword argument. This is intended to be a catch-all for any number of keyword arguments. Let’s write a long text.

A function with a positional-only parameter, a keyword-only parameter and variadic parameters:

def awesome_useless(a: int, /, b, **kwargs):
    """ Some useless function. """
    pass
Noteawesome_useless 
awesome_useless(
    a : int,
    /,
    b : Any,
    **kwargs : Any
    ):

Some useless function.

Parameters 
a : int
    
(missing description) 
b : Any
    
(missing description)

Function with all kinds of parameters:

def awesome_useless(x, /, y: int = 0, *, z: int = 0, **kwargs) -> None:
    """ Some useless function.

    Parameters
    ----------
    x : int
        Nothing to say about this.
    y : int
        Nothing to say about this.
    z : int
        Nothing to say about this.
    xx : int
        Nothing to say about this.
    """
    pass
Noteawesome_useless 
awesome_useless(
    x : Any,
    /,
    y : int = 0,
    *,
    z : int = 0,
    **kwargs : Any
    ) -> None:

Some useless function.

Parameters 
x : Any
    
Nothing to say about this. 
y : int = 0
    
Nothing to say about this. 
z : int = 0
    
Nothing to say about this. 
xx : int = None
    
Nothing to say about this.