Source code for torx.decorators.autodoc_decorators_m

"""Contains decorators to add automatically created nice documentation."""
from rich import inspect
import sys



def autodoc_module(mod_name):
    """
    Automatically create nice documentation for modules.

    Must be used as
        _repr_html_ = lambda: autodoc_module(__name__)
    to work properly.
    """
    inspect(sys.modules[mod_name], methods=True)




def autodoc_class(cls):
    """
    Automatically create nice documentation for classes and instances.

    Used as a decorator.
    """
    def __rich_repr__(self):
        """Advanced representation of the object."""
        # Inspect will print directly to the output
        inspect(self)
        # NOTE: We return None here, thus the output of __repr__ will be
        #       returned to the caller
        return None

    def __rich_help__(self=None, full=False):
        """Advanced help for the object."""
        # Either inspect the class or the object
        if self == None:
            to_inspect = __rich_help__.mytype
        else:
            to_inspect = self

        if not full:
            inspect(to_inspect, help=True, methods=True)
        else:
            inspect(to_inspect, all=True)

    # Jupyter uses repr_html which we set by our custom function
    # NOTE: Do not use __repr__ because rich inspect will call that function
    #       in its display, creating an infinite recursion
    cls._repr_html_ = __rich_repr__
    # Add class type to helper function for display of help of the class itself
    __rich_help__.mytype = cls
    cls.help = __rich_help__

    # Add help function to all methods in this class
    for attr, value in cls.__dict__.items():
        # NOTE: We currently cannot support internal functions with _ at the
        #       start
        # NOTE: All functions/methods have a method called mro which does not
        #       work with the code and needs to be excluded from autodoc
        if ("help" in attr) or ("mro" in attr) or ("_" in attr[0]):
            continue
        if callable(value):
            setattr(cls, attr, autodoc_function(value))

    return cls




def autodoc_function(func):
    """
    Automatically create nice documentation for functions.

    Used as a decorator.
    """
    def __rich_help__():
        inspect(__rich_help__.myfunc, help=True)

    __rich_help__.myfunc = func
    func.help = __rich_help__
    func._repr_html_ = __rich_help__
    return func