NumPy-style Docstrings

NumPy-style docstrings are a way of documenting your Python code in a standardized, machine-readable format that is easy to read and parse. They are named after the widely-used NumPy library, which popularized this style of documentation.

In this guide, we'll explain what NumPy-style docstrings are, why you should use them, and how to write them.

What are NumPy-style Docstrings?

NumPy-style docstrings are a variant of Google-style docstrings that use a structured format for describing your code. They consist of three main sections:

1. Summary Line: A one-line summary of what the function does.
2. Parameters: A list of the function's arguments and their types.
3. Returns: A description of what the function returns (if anything).

Here's an example:

def square(x):
    """
    Return the square of a number.

    Parameters
    ----------
    x : int or float
        The number to square.

    Returns
    -------
    float
        The square of `x`.
    """
    return x ** 2

In this example, the summary line briefly describes what the function does, while the parameters and returns sections provide more detailed information about the inputs and outputs of the function.

Why use NumPy-style Docstrings?

NumPy-style docstrings have several advantages over other forms of documentation:

1. Consistency: By using a standardized format, your documentation will be consistent across your entire project. This makes it easier for developers to understand your code and reduces confusion.
2. Readability: NumPy-style docstrings are designed to be easy to read and parse. This makes it more likely that other developers will read and understand your documentation.
3. Automation: Many tools (such as Sphinx) can automatically generate documentation from your NumPy-style docstrings. This saves you time and ensures that your documentation is always up-to-date.

How to write NumPy-style Docstrings

Here are some tips for writing effective NumPy-style docstrings:

1. Use one line for the summary, and keep it short and descriptive.
2. Use the NumPy docstring format to describe the parameters and returns of your function. This includes using sections for each parameter/return value, as well as specifying their types and descriptions.
3. Use clear and concise language. Avoid jargon and complex sentences.
4. Use examples to illustrate how your function should be used.

Here's an example of a more complex NumPy-style docstring:

def fibonacci(n):
    """
    Calculate the Fibonacci series.

    Compute the nth Fibonacci number, where:

    * Fibonacci(0) = 0
    * Fibonacci(1) = 1
    * Fibonacci(n) = Fibonacci(n-1) + Fibonacci(n-2)

    Parameters
    ----------
    n : int
        The index of the Fibonacci number to compute.

    Returns
    -------
    int
        The nth Fibonacci number.

    Examples
    --------
    >>> fibonacci(0)
    0
    >>> fibonacci(1)
    1
    >>> fibonacci(10)
    55
    """
    if n <= 1:
        return n
    else:
        return fibonacci(n-1) + fibonacci(n-2)

In this example, we use the NumPy-style docstring format to describe the parameters and returns of the fibonacci function, as well as providing examples of how to use it.

Conclusion

NumPy-style docstrings are a powerful tool for documenting your Python code. By using a standardized format, you can ensure that your documentation is consistent, easy to read, and machine-readable. Follow the guidelines outlined in this guide to write effective NumPy-style docstrings for your own projects.