A command line tool for generating Markdown documentation and .env files from pydantic BaseSettings.
Project description
⚙ 📝 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
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=
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
Updating existing documentation
You may want to generate the documentation into and 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:
<!-- 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 -->
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:
- Copy the built-in templates into a new directory:
mkdir custom_templates settings-doc templates --copy-to custom_templates
- Modify the template copies in
custom_templates
to suit your needs. You can keep only the modified ones assettings-doc
always falls back to the built-in ones. - 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
, which is the value of the--heading-offset
option, defaults to0
.fields
, which is the value ofBaseSettings.__fields__.values()
. In other words, a list of individual settings fields. Each field is then an instance ofModelField
.
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
.
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 withing 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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for settings_doc-0.5.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 13e442a9988bac3487401f99e740f3e5e6cae24a88cce896d362e1867cd1d3ee |
|
MD5 | e63fb92242dbda5b3d29840cd6b2db1e |
|
BLAKE2b-256 | 052d8f91a4529c1067891fef9cf0c683f5454d0b1afb8a22b3415324dcd34e0d |