search

CSCfi / rems

Resource Entitlement Management System is a tool for managing access rights to resources, such as research datasets.
MIT License
53 stars 22 forks source link

Move documentation to `configuration.md` #3071

Open Macroz opened 2 years ago

Macroz commented 2 years ago

We could have config-defaults.edn to contain just the defaults and use configuration.md for all the examples that are now there or in the comments.

We could add an automated check to see that every value is documented, so nothing is left out. This would improve the readability of the configuration optionts.

Macroz commented 2 years ago

I tried this out and it works. We have some options of what approach to use.

We can parse the keywords from configuration.md and compare to keys of config-defaults.edn. The only difficult part with this is the config keys where there is a complex structure. We can get a path out like :foo :bar but that is not easily modeled in Markdown. We'd have to parse headings, which is possible, or limit ourselves to some simple constructs. We could also always repeat the full path or only check the top level. Some of the values are keys also like :authentication :oidc and it would be nice to check that "enum-like" options are all covered, but that is perhaps too much work for the same reason.

I will let this simmer a bit. Today it feels best to just check and match the top level keys automatically, and trust the document writer that the options are there OK.