Materials-Consortia / Materials-Consortia/optimade-python-tools

Rendered docs do not show default pydantic field values

Open
#764 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

config docs enhancement
Dominant language
Python
Stars
91
Forks
54
PR merge metrics
No merged PRs in 30d

Description

I've just noticed that e.g. the server config docs do not show the default values for fields, e.g.,

2021-03-26-120207_615x149_scrot

I think it would be very helpful if they did; this may require an expansion of our existing manual configuration docs at https://www.optimade.org/optimade-python-tools/configuration/.

We should also consider removing internal classes like the pydantic Config of our ServerConfig model as it adds a lot of clutter (and this case, has a very confusing name...).

A related issue is the use of enums in our config, the allowed values of e.g. database_backend are not at all clear unless you scroll all the way down to the bottom of the page to the docs for the SupportedBackend type itself. There must be a better way of doing this...

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the rendered configuration documentation at optimade.org/optimade-python-tools/configuration/ and compare it with the ServerConfig and SupportedBackend material described in the issue. Trace how those models are exposed in the rendered docs, then define completion as showing field defaults, reducing internal Config clutter, and making allowed database_backend values clear.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.