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.

pip install docsplice

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 significant text.
    """

For more examples see Documentation

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

pytest docsplice

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

• e-mail: [email protected]

• see LICENSE