leaspy.utils.docs
=================

.. py:module:: leaspy.utils.docs


Attributes
----------

.. autoapisummary::

   leaspy.utils.docs.T
   leaspy.utils.docs.R
   leaspy.utils.docs.DEFAULT_INIT_DOC


Functions
---------

.. autoapisummary::

   leaspy.utils.docs.doc_with_
   leaspy.utils.docs.doc_with
   leaspy.utils.docs.doc_with_super


Module Contents
---------------

.. py:data:: T

.. py:data:: R

.. py:data:: DEFAULT_INIT_DOC
   :value: 'Initialize self.  See help(type(self)) for accurate signature.'


.. py:function:: doc_with_(target, original, mapping = None, **mapping_kwargs)

   
   Document (in-place) a function/class.

   Low-level version of :func:`.doc_with` (refer to its documentation)
   Will set `target.__doc__` in-place (not a decorator function).

   :Parameters:

       **target** : object
           Object to document (e.g. a function, a class, a given class method, ...).

       **original** : object
           Object to copy documentation from.

       **mapping** : dict
           Optional mapping to replace some terms (case-sensitive and word boundary aware) by others
           from the original docstring.

       **\*\*mapping_kwargs**
           Optional keyword arguments passed to :func:`._replace_terms` (flags=...).



   :Returns:

       target
           The (in-place) modified target object.











   ..
       !! processed by numpydoc !!

.. py:function:: doc_with(original, mapping = None, **mapping_kwargs)

   
   Factory of function/class decorator to use the docstring of `original`
   to document (in-place) the decorated function/class


   :Parameters:

       **original** : documented Python object
           The object to extract the docstring from

       **mapping** : dict[str, str], optional
           Optional mapping to replace some terms (case-sensitive and word boundary aware) by others
           from the original docstring.

       **\*\*mapping_kwargs**
           Optional keyword arguments passed to :func:`._replace_terms` (flags=...).



   :Returns:

       Function/class decorator
           ..











   ..
       !! processed by numpydoc !!

.. py:function:: doc_with_super(*, if_other_signature = 'raise', **doc_with_kwargs)

   
   Factory of class decorator that comment (in-place) all of its inherited methods without docstrings + its top docstring
   with the ones from its parent class (the first parent class with this method documented if multiple inheritance)


   :Parameters:

       **if_other_signature** : str
           Behavior if a documented method was found in parent but it has another signature:
               * ``'force'``: patch the method with the found docstring anyway (default)
               * ``'warn'``: patch the method but with a warning regarding signature mismatch
               * ``'skip'``: don't patch the method with the found docstring
               * ``'raise'``: raise a ValueError

       **\*\*doc_with_kwargs**
           Optional keyword arguments passed to :func:`.doc_with` (mapping=...).



   :Returns:

       Class decorator
           ..











   ..
       !! processed by numpydoc !!