Fix missing env var prefix in documentation

[dekkers]

Changes

Currently the environment variables in the documentation are wrong because they all miss the prefix. I think this is since we updated pydantic, pydantic-settings and settings-doc. I've fixed settings-doc to include the prefix, this PR changed settings-doc to my fork while we wait for the PR to be merged and a new version released to PyPI.

---

Checklist for code reviewers:

Copy-paste the checklist from the docs/source/templates folder into your comment.

---

Checklist for QA:

Copy-paste the checklist from the docs/source/templates folder into your comment.

[ammar92]

I'm still a bit hesitant when it comes to including external hotfixes because of the obvious reasons (keeping stuff up to date, missing dependabot alerts, etc.), but I think this could work as a temporary solution until, as you mentioned, this modification gets approved and merged in the designated package.

I was also wondering and currently still looking into this if it's possible to achieve this with the template (as it worked before?), but you've probably already looked into that.

Also, does this work for aliased fields? For example, the scheduler has a DEBUG variable, but based on the submitted PR I can infer that this would always produce prefixed fields like SCHEDULER_DEBUG and I'm not sure if that's correct and also loaded by pydantic-settings as the expected environment variable.

[ammar92]

I was also wondering and currently still looking into this if it's possible to achieve this with the template (as it worked before?), but you've probably already looked into that.

After some reading and experimenting, I found out we can reach the model_config.env_prefix attribute using the classes context variable in the template. With some effort we might be able to produce the same using only template code.

[dekkers]

I'm still a bit hesitant when it comes to including external hotfixes because of the obvious reasons (keeping stuff up to date, missing dependabot alerts, etc.), but I think this could work as a temporary solution until, as you mentioned, this modification gets approved and merged in the designated package.

In my experience maintainers rarely release new versions without merging open PRs or giving feedback.

I was also wondering and currently still looking into this if it's possible to achieve this with the template (as it worked before?), but you've probably already looked into that.

I couldn't figure it out quickly. Given that the env_prefix is part of pydantic-settings, in my opinion settings-doc should also support that and it is the right place to fix this.

Also, does this work for aliased fields? For example, the scheduler has a DEBUG variable, but based on the submitted PR I can infer that this would always produce prefixed fields like SCHEDULER_DEBUG and I'm not sure if that's correct and also loaded by pydantic-settings as the expected environment variable.

This is not correct, when there is an alias the alias is used as before. There are also unit tests in settings-doc for this.

After some reading and experimenting, I found out we can reach the model_config.env_prefix attribute using the classes context variable in the template. With some effort we might be able to produce the same using only template code.

You would also need to make sure that aliased fields don't get the prefix. It might be possible, but it would also be double work, because there is already a fix for settings-doc. And while we are dicussing this, everybody who goes to OpenKAT documentation gets the wrong information and potentially wastes a lot of time before figuring out that our documentation is currently just plain wrong.

[dekkers]

I forgot to mention the PR I opened, but it is radeklat/settings-doc#29

[ammar92]

In my experience maintainers rarely release new versions without merging open PRs or giving feedback.

While you might experience that, nothing indicates that this holds the same for this project, since the project doesn't have any real contributors expect for the owner (see issues and PRs).

I couldn't figure it out quickly. Given that the env_prefix is part of pydantic-settings, in my opinion settings-doc should also support that and it is the right place to fix this.

Agree, this should be part of settings-docs. But it isn't part of it yet, and maybe never will be. While with the templates it can already be achieved.

You would also need to make sure that aliased fields don't get the prefix. It might be possible, but it would also be double work, because there is already a fix for settings-doc.

Shouldn't be too hard to apply conditional formatting in Jinja templates: {% if field.alias %}{{ field.alias }}{% else %}{{ prefix }}{{ env_var }}{% endif %}

And while we are dicussing this, everybody who goes to OpenKAT documentation gets the wrong information and potentially wastes a lot of time before figuring out that our documentation is currently just plain wrong.

Agree, therefore we should quickly do something. Ultimately it comes down to whether we want a "corrupted" dependency tree or simply to use the template. I'll leave it up to you and @underdarknl