Auto-generating docstrings

Documenting existing code can be difficult and time-consuming because it requires understanding the code’s intent and purpose, which may not always be clear or immediately obvious.

Material for nbdev simplifies the task of documenting existing code by automatically creating Google-style docstrings for classes and methods which don’t have one. Material for nbdev internally uses the docstring-gen library and OpenAI’s Codex AI model for generating clear and informative docstrings.

Adding docstring

By running the following CLI command, you can add docstrings to a single Python file, a Jupyter notebook, or a directory containing these files.

Note

The OpenAI API uses API keys for authentication. Please create one and set it in the OPENAI_API_KEY environment variable before running the below command.

nbdev_mkdocs docstring generate -p {source_file_or_directory}

For example, a function like below without the docstring:

def concatenate_strings(s1: str, s2: str) -> str:
    if not isinstance(s1, str) or not isinstance(s2, str):
        raise TypeError("Both arguments should be strings.")
    return s1 + s2

will become similar to:

def concatenate_strings(s1: str, s2: str) -> str:
    """Concatenate two strings.

    Args:
        s1: First string
        s2: Second string

    Returns:
        The concatenated string

    Raises:
        TypeError: If s1 or s2 is not a string

    !!! note

        The above docstring is autogenerated by docstring-gen library (https://github.com/airtai/docstring-gen)
    """
    if not isinstance(s1, str) or not isinstance(s2, str):
        raise TypeError("Both arguments should be strings.")
    return s1 + s2

Regenerating the docstring

If you wish to regenerate the docstrings, you can re-run the command with the -f flag, which will remove the previous auto-generated docstrings and replace them with new ones.

nbdev_mkdocs docstring generate -p {source_file_or_directory} -f

Note

By default, the command only adds docstrings to missing functions and classes. It won't overwrite previously generated docstrings if the -f flag is not provided during re-run.

Regenerating the docstring without note

If you prefer not to include the text “autogenerated by docstring-gen library” in the generated docstrings, you can use the --no-include-auto-gen-txt flag when running the command.

nbdev_mkdocs docstring generate -p {source_file_or_directory} -f --no-include-auto-gen-txt

Now the docstring for the above function will look similar to:

def concatenate_strings(s1: str, s2: str) -> str:
    """Concatenate two strings.

    Args:
        s1: First string
        s2: Second string

    Returns:
        The concatenated string

    Raises:
        TypeError: If s1 or s2 is not a string
    """
    if not isinstance(s1, str) or not isinstance(s2, str):
        raise TypeError("Both arguments should be strings.")
    return s1 + s2

Note

The text “autogenerated by docstring-gen library” is used to identify which docstrings were generated by the library. When the --no-include-auto-gen-txt flag is used, this text will not be included in the generated docstrings. As a result, when re-running the command with the -f flag, these docstrings will not be replaced.”

Alternatively, you can manually delete the “autogenerated by docstring-gen library” (starting from the !!! note until the end) text from the classes and functions for which you think the auto-generated docstring is appropriate, and then re-run the command using the -f flag to update the remaining auto-generated docstrings.

Additional settings

In addition to the -f and --no-include-auto-gen-txt flags, you can also customize the behavior of the CLI command by adjusting other parameters such as --model, --temperature, etc., For more information on these options and how to use them, please refer to the OpenAI’s documentation.

Jupyter notebook extension

We have created a user-friendly notebook extension for the docstring-gen library. This extension provides a convenient way to document your code cell-by-cell, rather than having to document the entire notebook all at once. To install the extension, simply run the following commands in your terminal:

Note

Please ensure jupyter-contrib-nbextensions is installed before installing the docstring-gen library extension

jupyter nbextension install https://github.com/airtai/jupyter-docstring-gen/archive/main.zip --user
jupyter nbextension enable jupyter-docstring-gen-main/jupyter-docstring-gen

After successful installation, you will see a new button on your jupyter notebook toolbar. This button allows you to easily generate docstrings for your Python code and improve your documentation.

For more detailed information, please refer to this link.