Docstring Style Guide¶

This guide describes the docstring style used in sts-libs. We loosely follow Google-style docstrings with some specific conventions for examples.

Code Formatting¶

ruff formatter also formats code in docstrings:

hatch run format

or directly with ruff:

ruff format

This will ensure consistent formatting across the codebase and docstrings. With pre-commit hook installed, it will be automatically run on commit.

Single Example¶

def my_function():
    """Function description.

    Detailed description of what the function does.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Description of return value

    Example:
        ```python
        result = my_function(1, 2)
        ```
    """

Multiple Examples¶

def my_function():
    """Function description.

    Detailed description of what the function does.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Description of return value

    Examples:
        Basic usage:
        ```python
        result = my_function(1, 2)
        ```

        With optional parameters:
        ```python
        result = my_function(1, 2, optional=True)
        ```

        Error handling:
        ```python
        try:
            result = my_function(-1, 2)
        except ValueError:
            print("Invalid input")
        ```
    """

Key Points¶

Use descriptive text before each example
Use "Example:" for single examples, "Examples:" for multiple
Keep examples concise and focused
Include expected output in comments where relevant
Use markdown code blocks for proper rendering in mkdocs

Common Patterns¶

Class Examples¶

class MyClass:
    """Class description.

    Examples:
        Create with default settings:
        ```python
        obj = MyClass()
        ```

        Create with custom settings:
        ```python
        obj = MyClass(setting=True)
        ```
    """

Method Examples¶

def method(self):
    """Method description.

    Example:
        ```python
        obj = MyClass()
        result = obj.method()  # Returns expected value
        ```
    """

Function Examples¶

def function():
    """Function description.

    Examples:
        Basic usage:
        ```python
        function()
        ```

        With error handling:
        ```python
        try:
            function()
        except Error:
            handle_error()
        ```
    """

Previewing Documentation¶

To see how your docstrings are rendered in mkdocs:

Run the documentation server locally:

hatch run docs:serve

Open your browser to http://127.0.0.1:8000

This allows you to verify that your examples are properly rendered in the documentation.

Tips for Writing Good Examples¶

Be Concise: Examples should demonstrate one specific use case clearly
Show Real Usage: Use realistic variable names and values
Include Context: Add brief descriptions before examples
Show Outputs: Use comments to indicate expected return values or outputs
Error Cases: Include examples of handling common errors when relevant