Dataclass-Documenter 2024.1

Generate commented YAML input files and markdown documentation from dataclasses.

---

title: README author: Jan-Michael Rye

Synopsis

A Python package and command-line utility to automate documentation of Python dataclasses. It can generate the following:

• Commented YAML input files which can be used as user configuration files.
• Markdown output for README files which contain the dataclass docstring and commented YAML.

Links

GitLab

• Homepage
• Source
• Documentation
• Issues
• GitLab package registry

Usage

Command-Line Utility

The package installs the dataclass_documenter which can be used to generate the output from the command-line.

$ dataclass_documenter -h
usage: dataclass_documenter [-h] [-m] [-l LEVEL] dataclass

Generate Markdown or YAML for a dataclass. Note that this will load the module
containing the target dataclass and thus execute any top-level code within
that module.

positional arguments:
  dataclass             The target dataclass, specified as
                        "<module|file>:<class>", e.g. "mypkg.mod1:MyDataclass"
                        or "path/to/src.py:MyDataclass".

options:
  -h, --help            show this help message and exit
  -m, --markdown        Output Markdown documentation instead of just the YAML
                        input file.
  -l LEVEL, --level LEVEL
                        Nesting level of output. For YAML this defines the
                        indentation level. For Markdown this defines the
                        header level.

Python API

The package can also be used directly via its API.

# Import the documenter class.
from dataclass_documenter import Dataclass_Documenter

# Initialize it with a custom dataclass. Here we assume that MyDataclass is a
defined dataclass.
dado = Dataclass_Documenter(MyDataclass)

# Retrieve YAML and/or Markdown text.
yaml_output = dado.get_yaml()
markdown_output = dado.get_markdown()

Example

The following is an example using the dataclasses defined for the unit tests.

Dataclass Definitions

Example dataclasses to show the correpondence between the definition and the generated documentation.

@dataclasses.dataclass
class NestedExampleDataclass:
    """
    Nested dataclass to test recursive documentation.

    Parameters:
        nested_string:
            A string parameter of the nested dataclass.

        nested_number:
            An numerical parameter of the nested dataclass
    """

    nested_string: str = "Another string value."
    nested_number: int | float = 5


@dataclasses.dataclass
class ExampleDataclass:
    """
    Brief description for example dataclass.

    This is a longer description. This dataclass is used for testing and
    generating an example in the README.

    Parameters:
        string:
            A string parameter.

        nested_dataclass:
            A nested dataclass that encapsulates its own parameters.

        integer:
            An integer parameter.

        floats:
            A list of floats.

        opt_string:
            An optional string that may be None.
    """

    string: str
    nested_dataclass: NestedExampleDataclass
    integer: int = 7
    floats: list[float] = dataclasses.field(default_factory=list)
    opt_string: Optional[str] = None
    undocumented_string: str = "Intentionally undocumented string."

Markdown Output

The following is the Markdowna and YAML output automatically generated from the example dataclasses.

ExampleDataclass

Brief description for example dataclass.

This is a longer description. This dataclass is used for testing and generating an example in the README.

Input

# Input for ExampleDataclass

# A string parameter.
# Type: str [REQUIRED]
string: ...

# A nested dataclass that encapsulates its own parameters.
nested_dataclass:
  # A string parameter of the nested dataclass.
  # Type: str [OPTIONAL]
  nested_string: Another string value.

  # An numerical parameter of the nested dataclass
  # Type: UnionType[int, float] [OPTIONAL]
  nested_number: 5

# An integer parameter.
# Type: int [OPTIONAL]
integer: 7

# A list of floats.
# Type: list[float] [OPTIONAL]
floats: []

# An optional string that may be None.
# Type: str [OPTIONAL]
opt_string: null

# Undocumented.
# Type: str [OPTIONAL]
undocumented_string: Intentionally undocumented string.