Idea: refactor config docs with custom sphinx role
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 1.1k
- Forks
- 564
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 29
Description
Currently, the config docs are a bit scattered as mentioned in https://youtu.be/SevMNjTDTzs.
The list of config options is quite useful to gather an overview. Yet, the list might be incomplete and when we would split up the stuffed "Install Guide/Configuration" page into more pages on topics, it still would be a good thing to have a complete list of linkable and referencable options.
While hacking on a smallish PR for #6953, I had an idea for this. There are multiple extensions that provide custom roles, including rendering, linking, referencing and generating an index list.
Adding such a small extension to our Sphinx based guide (or develop as a separate extension) would make this possible. There is no maintained generic extension or builtin support to create these. (So we have to create an extension ourselfs...)
To provide an example: in a section about some configuration, one might add the following documentation about a setting:
.. dvoption::
:key: <key string>
:default: <default value>
:allowedValues: ...
:alias: <add old names here>
:type: <mpconfig|db|...>
:summary: <a short description>
(...)
This config option allows you to ... (long description here)
This would be rendered in place plus added to an index, that might be printed in a dedicated place by using .. dvoptionslist::.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the Sphinx-based guide and the existing Install Guide/Configuration page to map how configuration options are currently documented. Compare the proposed dvoption and dvoptionslist roles with available Sphinx extensions, then define the extension scope and a complete, linkable configuration index before implementation.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100