DocSplice

Docstring splicing for python functions 🧬

This project allows you to splice docstrings for python functions in a convenient way using a functional decorator. This enables you to more easily create consistent documentation for your API without needing to duplicate docstring sections for functions that have the same parameter descriptions or other related content. This will ease the maintenance burden for your package documentation since the content of your function or class documentation reside in a single location in the source code, instead of being duplicated within each function body.

Install

pip install docsplice

Use

Pulling parameters from multiple sources

import docsplice as doc


def fun1(a):
    """
    Do something with a number.

    Parameters
    ----------
    a : int
        The number.
    """
    
def fun2(b=0):
    """
    Another function that does something with an integer.
    
    Parameters
    ----------
    b : int, optional
        Another number! By default 0.
    """

@doc.splice({'Parameters[a]': fun1,
             'Parameters[b] as n=7': fun2}) 
def combined(a, n=7):
    """
    Some profound computation. Parameter descriptions follow:
    """

The Parameters section in the docstring for combined has been created by the splice decorator. Inspecting the object in an interactive terminal reveals that the docstring has been filled:

combined??

Signature: combined(a, n=7)
Docstring:
Some profound computation. Parameter descriptions follow:

Parameters
----------
a : int
    The number.
n : int, optional
    Another number! By default 7.
Source:   
@doc.splice({'Parameters[a]': fun1,
             'Parameters[b] as n=7': fun2}) 
def combined(a, n=7):
    """
    Some profound computation. Parameter descriptions follow:
    """

Test

The test suite contains further examples of how DocSplice can be used. Testing is done with pytest:

pytest docsplice

Contribute

Contributions are welcome!

1. Fork it!
2. Create your feature branch
   git checkout -b feature/rad
3. Commit your changes
   git commit -am 'Add something rad'
4. Push to the branch
   git push origin feature/rad
5. Create a new Pull Request

Contact

• e-mail: hannes@saao.ac.za

License

• see LICENSE