Document the Pydantic models for TOML validation with autodoc-pydantic?

[tomschr]

Situation

In #174 (comment), Sushant correctly found out that default values aren't cleanly defined. This makes it harder to a) write it in the TOML file, and b) document it for the result documentation.

Sushant suggested two possible options:

1. Keep the line active but set it to a 'disabled' state, like port = 0. You can then update the comment to: # port(int): Port number. Set to 80 for default or 0 to disable. This keeps the parser logic simple and the key visible to users.
2. We could tweak toml_parser.py to look for an explicit default in the comment, for example: # port(int): Port number. Default: 80. If the parser finds this, it uses it for the RST regardless of whether the TOML line is commented out.

We could get rid of all the half-baked solutions by using autodoc-pydantic.

Use Case

Makes it easier for us developers to document it in the TOML file and to get a nicely formatted reference.

Possible Implementation

Create a proof-of-concept and integrate it into our existing documentation.

Still we need to discuss how we want to have our example file:

• As a development config which any user can use directly from the repo. OR
• As a production config which documents the parts for Docserv. We may expose paths and other values that we don't want to make public, or do we?