Fix #171: Document ENV config TOML file

[tomschr]

• Generate the RST from TOML file through a Python script (toml_parser.py). It can be executed as a standalone script or is integrated into Sphinx.
• Enhance conf.py to read the TOML config(s) and create the generated file. The generated file is included in reference/env-toml/index.rst.
• The generated file has a different extension than .rst (actually .rst.inc). This was necessary otherwise you get a warning from Sphinx about "duplicate labels".
• Enrich the TOML file with comments similar to "docstrings": it uses the syntax KEYNAME(TYPE): DESCRIPTION as a "self-documenting" approach.
• Currently, the standard tomllib library doesn't preserve comments. To not rely on a different library, we need to read it line by line. 😞
• There is a small optimization in the conf.py file: the .rst.inc file is only generated when the TOML file has a newer date.

Additional changes that were needed:

• Introduce a new github-action group in pyproject.toml. This requires tests and docs as conf.py requires Sphinx now.
• Adjust the workflows/ci.yml to use the new github-action group.
• Update the uv.lock file to contain this new group too.

Screenshot

Meaning of the callouts in the image:

1. The title from the reference/env-toml/index.rst
2. The introductory paragraph, also from reference/env-toml/index.rst
3. The TOML section taken from the etc/docbuild/env.example.toml
4. The description of the section taken from a comment of etc/docbuild/env.example.toml
5. Also a comment before the key/value pair from etc/docbuild/env.example.toml

[github-actions]

Coverage Report

For commit 14c8028

Click to expand Coverage Report

  Name                                           Stmts   Miss Branch BrPart  Cover
  --------------------------------------------------------------------------------
+ src/docbuild/cli/cmd_check/process.py             60      0     22      1  98.8%
+ src/docbuild/utils/pidlock.py                     79      1     14      1  97.8%
+ src/docbuild/cli/cmd_validate/process.py         178      3     52      2  97.8%
+ src/docbuild/config/xml/stitch.py                 48      1     12      1  96.7%
+ src/docbuild/cli/callback.py                      35      0     10      2  95.6%
+ src/docbuild/cli/cmd_metadata/metaprocess.py     167     10     42      7  91.9%
- src/docbuild/cli/cmd_config/__init__.py            9      1      0      0  88.9%
- src/docbuild/cli/cmd_cli.py                       86     11      6      3  84.8%
- src/docbuild/cli/cmd_check/__init__.py            18      5      2      0  65.0%
- src/docbuild/cli/cmd_build/__init__.py            13      5      0      0  61.5%
- src/docbuild/cli/cmd_metadata/__init__.py         27     10      2      0  58.6%
- src/docbuild/cli/cmd_config/environment.py        11      6      2      0  38.5%
  --------------------------------------------------------------------------------
+ TOTAL                                           2744     53    638     17  97.8%
  
  47 files skipped due to complete coverage.

[sushant-suse]

The port key in the [server] section is now active (uncommented) with a default of 80. If we want the example to stay 'safe' by default, we might want to keep it commented out, though the parser should still be able to show it as an option if configured to do so. WDYT?

[tomschr]

You make an excellent observation! 👍

I'm not sure yet how to deal with such values that are disabled in the TOML, but should be displayed in the doc. Any idea?

[sushant-suse]

That’s the classic 'Reference vs. Example' dilemma. Since we want to keep the TOML safe but the docs informative, here are two suggestions that can be done:

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.

Personally, I like the option 1. It is quite common in TOML examples and ensures the user does not have to guess where to add the key later. What do you think?

[sushant-suse]

• Generate the RST from TOML file through a Python script (toml_parser.py). It can be executed as a standalone script or is integrated into Sphinx.
• Enhance conf.py to read the TOML config(s) and create the generated file. The generated file is included in reference/env-toml/index.rst.
• The generated file has a different extension than .rst (actually .rst.inc). This was necessary otherwise you get a warning from Sphinx about "duplicate labels".
• Enrich the TOML file with comments similar to "docstrings": it uses the syntax KEYNAME(TYPE): DESCRIPTION as a "self-documenting" approach.
• Currently, the standard tomllib library doesn't preserve comments. To not rely on a different library, we need to read it line by line. 😞
• There is a small optimization in the conf.py file: the .rst.inc file is only generated when the TOML file has a newer date.

Additional changes that were needed:

• Introduce a new github-action group in pyproject.toml. This requires tests and docs as conf.py requires Sphinx now.
• Adjust the workflows/ci.yml to use the new github-action group.
• Update the uv.lock file to contain this new group too.

Screenshot

Meaning of the callouts in the image:

1. The title from the reference/env-toml/index.rst
2. The introductory paragraph, also from reference/env-toml/index.rst
3. The TOML section taken from the etc/docbuild/env.example.toml
4. The description of the section taken from a comment of etc/docbuild/env.example.toml
5. Also a comment before the key/value pair from etc/docbuild/env.example.toml

Hi @tomschr thanks a lot for the awesome work.

The "Documentation as Code" approach is excellent. Syncing the documentation directly with env.example.toml ensures the reference guide never goes stale. Small feedback(s):

• toml_parser.py: Add encoding="utf-8" to read_text() and write_text() calls for cross-platform (Windows) reliability.
• conf.py: Fix the filename typo in the comment (toml_doc_generator.py toml_parser.py).
• env.example.toml: The new key(type): description syntax is clean and well-applied across all sections.

Great engineering to keep the build dependency-free. Approved.