radeklat/settings-doc

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

settings-doc's Issues

It appears sub-models are not supported

Not sure if I'm right, but it appears only the root fields of BaseSettings are exposed correctly.

From pydantic docs:

class SubModel(BaseModel):
    foo = 'bar'
    apple = 1

class Settings(BaseSettings):
    more_settings: SubModel = SubModel()
    class Config:
        env_prefix = "QUX__"
        env_nested_delimiter = "__"

generates support for QUX__MORE_SETTINGS__FOO and QUX__MORE_SETTINGS__APPLE env vars.

I haven't yet checked if this is doable by overriding templates (it would be nice to explain that in README, if that's the case), but even if it is doable, I believe this should work by default.

Usage with multiple BaseSettings classes

Hello, great project! This is exactly what people need.

In my case I need env variable docs for all new variables. And if I added a new class, then I want documentation to be generated for it and I didn't have to specify it class manualy via -c.

How can I use settings-doc if I have multiple settings classes? I would not like to indicate it by hand.

Have you thought about the possibility of passing only the module path or a regular expression or something like that so that the utility can independently find all the classes with settings and return results for them?

Thx, I can help with realization:)

Custom Filter for Jinja Renderer

Hello @radeklat , thanks for the last update to expose classes. So far, I am enjoying my experience in auto generating configurations for my apps :D.

Currently I am contemplating the solution for one of my use cases. I want to display the class title and render each classes sorted by their titles. I displayed the title by using the following macro:

{% macro class_title(class) -%}
{% if class.Config|attr('title') -%}
{{ class.Config.title }}
{%- else -%}
{{ class.__name__ }}
{%- endif %}
{%- endmacro %}

However, I reached a conundrum while trying to sort the classes by their title. After some tinkering, I figured out a way to achieve this is to add custom filters. So I modified the main.py (for testing purpose):

class_title = env.globals["class_title"] = lambda x: x.Config.title if hasattr(getattr(x, 'Config', None), 'title') else x.__name__
env.filters["sort_title"] = lambda x: list(sorted(x, key=class_title))

And I use them in the following way:

{% for class in classes|sort_title %}
{{ heading(2) }} {{ class_title(class) }}
{% endfor %}

I am wondering what are your thoughts on this and if it is worth supporting custom filters without having to modify the main.py. I will gladly write a pull request if you think that this is a good idea/feature to support.

Issue rendering submodules

This is a follow-up from #15 .

Admittedly, what I'm trying to do is somewhat unorthodox. I'm not in love with Pydantic's "nested delimiter" feature. Personally, I'd rather not leak the structure of my configuration model outside of my application. If I decide to restructure my configuration models, I don't want everything that uses my application to need to modify the environment variables they set. In other words, I view the set of configuration parameters (i.e. environment variable names) as an interface that I'd like to be open to extension but closed for modification.

I have my configuration defined like this:

from pydantic_settings import BaseSettings, SettingsConfigDict

PREFIX = "MY_APP_"


class SubConfig(BaseSettings):
    model_config = SettingsConfigDict(env_prefix=f"{PREFIX}_SUB_", extra="ignore")
    field_a: int
    field_b: float


class Config(BaseSettings):
    model_config = SettingsConfigDict(env_prefix=PREFIX, extra="ignore")

    field_1: str
    field_2: bool
    sub: SubConfig

In practice, this lets me define environment variables like MY_APP_SUB_FIELD_A, without the need of a specific delimiter. settings-doc renders it as follows:

# `MY_APP_FIELD_1`

**Required**

# `MY_APP_FIELD_2`

**Required**

# `MY_APP_SUB`

**Required**

I'd like for settings-doc to traverse the subconfig and generate documentation for its members. Any help is appreciated.

Unstable output ordering

I use a combination of --module and --class to specify Settings sources.
The order how they appear in the output is not stable and changes between runs.
This is especially problematic with pre-commit, which fails if it detects a file change.

I think this can be fixed by sorting

settings-doc/src/settings_doc/main.py

Lines 148 to 150 in 982d3aa

	settings: Set[Type[BaseSettings]] = importing.import_class_path(tuple(class_path)).union(
	importing.import_module_path(tuple(module_path))
	)

e.g. with

sorted(settings, key=str)

However, I think keeping the order of Settings classes the same as in the input is more user friendly, in that case I think an ordered set will need to be used.

Idea: pre-commit-hook

I think it would be a very useful feature to expose this project as a pre-commit-hook.

This way, people would be able to, say, update their README.md file automatically on each change, without running multi-step CI jobs, or doing that manually.