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
• Issues
• Documentation
• GitLab package registry

Other Repositories

• Python Package Index (PyPI)
• Software Heritage

Usage

Command-Line Utility

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

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  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 DataclassDocumenter

# Initialize it with a custom dataclass. Here we assume that MyDataclass is a
defined dataclass.
dado = DataclassDocumenter(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:
            A numerical parameter of the nested dataclass
    """

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


@dataclasses.dataclass
class ExampleDataclass:  # pylint: disable=too-many-instance-attributes
    """
    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.

        nested_dataclass_list:
            List of nested dataclass objects for testing composite types.
    """

    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."
    nested_dataclass_list: list[NestedExampleDataclass] = dataclasses.field(
        default_factory=list
    )
    nested_dataclass_dict: dict[str, NestedExampleDataclass] = dataclasses.field(
        default_factory=dict
    )

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

# 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.

  # A 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.

# List of nested dataclass objects for testing composite types.
# Type: list[NestedExampleDataclass] [OPTIONAL]
nested_dataclass_list: []
  # NestedExampleDataclass

  # A string parameter of the nested dataclass.
  # Type: str [OPTIONAL]
  # - nested_string: Another string value.

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

# Undocumented.
# Type: dict[str, NestedExampleDataclass] [OPTIONAL]
nested_dataclass_dict: {}
  # String key
  # key:
    # NestedExampleDataclass

    # A string parameter of the nested dataclass.
    # Type: str [OPTIONAL]
    # nested_string: Another string value.

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