:construction: Initial changes for documenting envvars

maykinmedia / open-api-framework

The Open API framework powers the open source registration components like Open Zaak en Open Klant.

MIT License

0 stars 0 forks source link

:construction: Initial changes for documenting envvars #22

Open stevenbal opened 1 month ago

stevenbal commented 1 month ago

Closes https://github.com/open-zaak/open-zaak/issues/1649 partly

Based on #19

[ ] how to deal with differing defaults per settings? docker sometimes has different defaults from base

stevenbal commented 3 weeks ago

@annashamray let me know if this approach is something that you think is worthwhile, I think it could save us a lot of hassle when it comes to documenting envvars (especially those that are used by every project). Here is an example of what it looks like after running the command: https://github.com/maykinmedia/objecttypes-api/blob/66a942d613776cb1766d3da025ce5e321103cf40/docs/env_config.rst

annashamray commented 3 weeks ago

I quite like it! It also forces you to write what the env variable actually does, which is a good thing for me. Do you think that generating docks for djang-setup-configuration would be redundant in this case?

stevenbal commented 3 weeks ago

Do you think that generating docks for djang-setup-configuration would be redundant in this case?

I'm not sure, since there already were docs for those I excluded them, also because they maybe require a bit more explanation to describe the ConfigurationSteps as a whole. Also the generated docs for setup-configuration relies on reusing the model field help_texts, so I think that's still good to have