Describe

Configuration documentation and description utilities.

describe

Configuration description and documentation utilities.

Public API

• describe_single: Generate docs for a single config class
• describe_configs: Generate docs for multiple config classes
• generate_env_example: Convenience wrapper for .env.example generation

OutputFormat module-attribute

OutputFormat = Literal[
    "table", "markdown", "json", "html", "dotenv"
]

describe_single

describe_single(
    config_cls: type[DotEnvConfig],
    output_format: OutputFormat = "table",
    output: str | Path | None = None,
    line_ending: str | None = None,
) -> str

Generate documentation for a single config class.

Parameters:

Name	Type	Description	Default
config_cls	type[DotEnvConfig]	The DotEnvConfig subclass to describe	required
output_format	OutputFormat	Output format - "table" (default), "markdown", "json", "html", or "dotenv"	'table'
output	str | Path | None	Optional file path to save the output to	None
line_ending	str | None	Line ending to use. If None, uses platform default (os.linesep)	None

Returns:

Type	Description
str	Formatted string describing the configuration

Raises:

Type	Description
ValueError	If output_format is not recognized

Example

AppConfig.describe(output_format="markdown", output="docs/config.md")
AppConfig.describe(output_format="dotenv", output=".env.example")

Source code in dotenvmodel/describe/__init__.py

def describe_single(
    config_cls: type[DotEnvConfig],
    output_format: OutputFormat = "table",
    output: str | Path | None = None,
    line_ending: str | None = None,
) -> str:
    """Generate documentation for a single config class.

    Args:
        config_cls: The DotEnvConfig subclass to describe
        output_format: Output format - "table" (default), "markdown", "json", "html", or "dotenv"
        output: Optional file path to save the output to
        line_ending: Line ending to use. If None, uses platform default (os.linesep)

    Returns:
        Formatted string describing the configuration

    Raises:
        ValueError: If output_format is not recognized

    Example:
        ```python
        AppConfig.describe(output_format="markdown", output="docs/config.md")
        AppConfig.describe(output_format="dotenv", output=".env.example")
        ```
    """
    line_ending = line_ending if line_ending is not None else os.linesep

    truncate = output_format not in ("json", "dotenv", "html")
    class_name, prefix, fields = describe_class(config_cls, truncate=truncate)

    if output_format == "table":
        result = render_table(class_name, prefix, fields, line_ending)
    elif output_format == "markdown":
        result = render_markdown(class_name, prefix, fields, line_ending)
    elif output_format == "json":
        result = render_json(class_name, prefix, fields, line_ending)
    elif output_format == "html":
        result = render_html(class_name, prefix, fields, line_ending)
    elif output_format == "dotenv":
        result = render_dotenv(class_name, prefix, fields, line_ending)
    else:
        raise ValueError(f"Unknown output_format: {output_format}")

    if output:
        Path(output).write_text(result, encoding="utf-8")

    return result

describe_configs

describe_configs(
    config_classes: list[type[DotEnvConfig]],
    output_format: OutputFormat = "table",
    output: str | Path | None = None,
    line_ending: str | None = None,
) -> str

Generate documentation for multiple config classes.

Parameters:

Name	Type	Description	Default
config_classes	list[type[DotEnvConfig]]	List of DotEnvConfig subclasses to describe	required
output_format	OutputFormat	Output format - "table", "markdown", "json", "html", or "dotenv"	'table'
output	str | Path | None	Optional file path to save the output to	None
line_ending	str | None	Line ending to use. If None, uses platform default	None

Returns:

Type	Description
str	Formatted string describing all configurations

Example

describe_configs([AppConfig, DatabaseConfig], output_format="markdown",
                 output="docs/configuration.md")

Source code in dotenvmodel/describe/__init__.py

def describe_configs(
    config_classes: list[type[DotEnvConfig]],
    output_format: OutputFormat = "table",
    output: str | Path | None = None,
    line_ending: str | None = None,
) -> str:
    """Generate documentation for multiple config classes.

    Args:
        config_classes: List of DotEnvConfig subclasses to describe
        output_format: Output format - "table", "markdown", "json", "html", or "dotenv"
        output: Optional file path to save the output to
        line_ending: Line ending to use. If None, uses platform default

    Returns:
        Formatted string describing all configurations

    Example:
        ```python
        describe_configs([AppConfig, DatabaseConfig], output_format="markdown",
                         output="docs/configuration.md")
        ```
    """
    if not config_classes:
        return "No configuration classes provided."

    line_ending = line_ending if line_ending is not None else os.linesep

    if output_format == "json":
        results = []
        for cls in config_classes:
            class_name, prefix, fields = describe_class(cls, truncate=False)
            results.append(build_json_data(class_name, prefix, fields))
        result = json.dumps(results, indent=2)
        if line_ending != "\n":
            result = result.replace("\n", line_ending)
    else:
        sections = [
            describe_single(cls, output_format=output_format, line_ending=line_ending)
            for cls in config_classes
        ]

        if output_format == "table":
            separator = line_ending + line_ending
        elif output_format in ("markdown", "html"):
            separator = line_ending + line_ending + "---" + line_ending + line_ending
        else:
            separator = line_ending + line_ending
        result = separator.join(sections)

    if output:
        Path(output).write_text(result, encoding="utf-8")

    return result

generate_env_example

generate_env_example(
    config_cls: type[DotEnvConfig],
    output: str | Path | None = None,
) -> str

Generate a .env.example file for onboarding.

Convenience wrapper around describe_single with output_format="dotenv".

Parameters:

Name	Type	Description	Default
config_cls	type[DotEnvConfig]	The DotEnvConfig subclass to generate example for	required
output	str | Path | None	Optional file path to save the .env.example to	None

Returns:

Type	Description
str	.env.example file content as a string

Example

AppConfig.generate_env_example(output=".env.example")

Source code in dotenvmodel/describe/__init__.py

def generate_env_example(
    config_cls: type[DotEnvConfig],
    output: str | Path | None = None,
) -> str:
    """Generate a .env.example file for onboarding.

    Convenience wrapper around describe_single with output_format="dotenv".

    Args:
        config_cls: The DotEnvConfig subclass to generate example for
        output: Optional file path to save the .env.example to

    Returns:
        .env.example file content as a string

    Example:
        ```python
        AppConfig.generate_env_example(output=".env.example")
        ```
    """
    return describe_single(config_cls, output_format="dotenv", output=output)