Hey All,
For the past few days, I've been trying to improve the documentation
style for Mailman Core's config options. Internally, Mailman has
all configurations defined in an ini formatted schema.cfg file, which
serves as a schema for our zope.configuration library. We had that file
simply embedded in the sphinx documentation previously as a wall of text.
I ended up writing a Sphinx (our documentation generator) plugin which parses the config file and presents the same documentation with more bells and whistles so it is easier to lookup and link sections and config options.[1]
The process of doing that was fun and I learnt how to write a simple sphinx plugin, so yay! It treats the comments above each config option in the ini file as it's doc and basically generates ReST text that it passes to Sphinx to parse and convert to the markup format that you see in browser. You can look at it in the source repo[2] .
Do note that not all sections are documented yet, I am still figuring out what
would be a good way to document template sections like [plugins.master]
and other similar sections of that kind.
[1]: https://gnu-mailman--667.org.readthedocs.build/projects/mailman/en/667/src/m... ((URL is for the PR, the main doc seems like is serving the cached version from an older build). [2]: https://gitlab.com/mailman/mailman/-/blob/master/_ext/configplugin.py
-- thanks, Abhilash Raj (maxking)