settings-doc 2.0.0

A command line tool for generating Markdown documentation and .env files from pydantic BaseSettings.

⚙ 📝  Settings DocGen  📝 ⚙

A command line tool for generating Markdown documentation and .env files from pydantic.BaseSettings.

The same way you are able to generate OpenAPI documentation from pydantic.BaseModel, settings-doc allows you to generate documentation from pydantic.BaseSettings.

It is powered by the Jinja2 templating engine and Typer framework. If you don't like the built-in templates, you can easily modify them or write completely custom ones. All attributes of the BaseSettings models are exposed to the templates.

Table of content

• Installation
• Usage
  • Minimal example
  • Class auto-discovery
  • Adding more information
  • Updating existing documentation
• Advanced usage
  • Custom templates
  • Custom settings attributes in templates
• Features overview
  • Markdown
  • .env

Installation

pip install settings-doc

Usage

See settings-doc --help for all options.

Minimal example

Let's assume the following BaseSettings in src/settings.py of a project:

from pydantic import BaseSettings

class AppSettings(BaseSettings):
    logging_level: str

You can generate a Markdown documentation into stdout with:

settings-doc generate --class src.settings.AppSettings --output-format markdown

Which will output:

# `LOGGING_LEVEL`

**Required**

Similarly, you can generate a .env file for local development with:

settings-doc generate --class src.settings.AppSettings --output-format dotenv

Which will output:

LOGGING_LEVEL=

Class auto-discovery

If you have a module with a single settings class or want to load multiple classes at once as a source, you can also use the --module option. The following example works exactly like the one above and will use the AppSettings class automatically.

settings-doc generate --module src.settings --output-format dotenv

If multiple classes contain a field with the same name, all instances will appear in the output.

Adding more information

You can add any extra field parameters to the settings. By default, settings-doc will utilise the default value, whether the parameter is required or optional, description, example value, and list of possible values:

from pydantic import BaseSettings, Field

class AppSettings(BaseSettings):
    logging_level: str = Field(
        "WARNING",
        description="Log level.",
        example="`WARNING`",
        possible_values=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
    )

Which will generate the following markdown:

# `LOGGING_LEVEL`

*Optional*, default value: `WARNING`

Log level.

## Examples

`WARNING`

## Possible values

`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`

or .env file:

# Log level.
# Possible values:
#   `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
# LOGGING_LEVEL=WARNING

You can find even more complex usage of settings-doc in one of my other projects.

Updating existing documentation

It is possible to generate documentation into an existing document. To fit with the heading structure, you can adjust the heading levels with --heading-offset. Additionally, you can specify the location where to generate the documentation with two marks set by --between <START MARK> <END MARK>.

Let's assume your README.md looks like this:

# My app

This app is distributes as a docker image and configurable via environment variables. See the list below.

# Environment variables
<!-- generated env. vars. start -->
<!-- generated env. vars. end -->

When you run:

settings-doc generate \
  --class src.settings.AppSettings \
  --output-format markdown \ 
  --update README.md \
  --between "<!-- generated env. vars. start -->" "<!-- generated env. vars. end -->" \
  --heading-offset 1

the updated README.md will get only the specified location overwritten:

# My app

This app is distributes as a docker image and configurable via environment variables. See the list below.

# Environment variables
<!-- generated env. vars. start -->
## `LOGGING_LEVEL`

*Optional*, default value: `WARNING`

Log level.

### Examples

`WARNING`

### Possible values

`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
<!-- generated env. vars. end -->

Advanced usage

Custom templates

settings-doc comes with a few built-in templates. You can override them or write completely new ones.

To just modify the existing ones:

1. Copy the built-in templates into a new directory:

   mkdir custom_templates
   settings-doc templates --copy-to custom_templates
   

2. Modify the template copies in custom_templates to suit your needs. You can keep only the modified ones as settings-doc always falls back to the built-in ones.
3. Use them when generating the documentation:

   settings-doc generate \
     --class src.settings.AppSettings \
     --output-format dotenv \
     --templates custom_templates
   

To create new ones, create a folder and then a Jinja2 template with a file names <OUTPUT_FORMAT>.jinja. Then simply reference both in the command line options:

mkdir custom_templates

echo "{{ field.title }}" > custom_templates/only_titles.jinja

settings-doc generate \
 --class src.settings.AppSettings \
 --output-format only_titles \
 --templates custom_templates

Custom settings attributes in templates

By default, there are several variables available in all templates:

• heading_offset - the value of the --heading-offset option. Defaults to 0.
• fields the value of BaseSettings.__fields__.values(). In other words, a list of individual settings fields. Each field is then an instance of ModelField. If multiple classes are used to generate the documentation, ModelFields from all classes are collected into fields. The information about original classes is not retained.
• classes - a dictionary, where keys are the BaseSettings sub-classes and values are lists of extracted ModelFields of that class. This can be used for example to split individual classes into sections.

Extra parameters unknown to pydantic are stored in field.field_info.extra. Examples of such parameters are example and possible_values.

Even the bare ModelField without any extra parameters has a large number of attributes. To see them all, run this settings-doc with --format debug.

To access information from the BaseSettings classes, use the classes variable in the templates:

{% for cls, fields in classes.items() %}
# {{ cls.__name__ }}
{% endfor %}

Features overview

• Output into several formats with --output-format: markdown, dotenv
• Writes into stdout by default, which allows piping to other tools for further processing.
• Able to update specified file with --update, optionally between two given string marks with --between. Useful for keeping documentation up to date.
• Additional templates and default template overrides via --templates.

Markdown

• Allows setting a --heading-offset to fit into existing documentation.
• Intelligently formats example values as:
  • Single line if all values fit within 75 characters.
  • List of values if all values won't fit on a single line.
  • List of <VALUE>: <DESCRIPTION> if example values are tuples of 1-2 items.

.env

• Leaves environment variables commented if they have a default value as the app doesn't require them.