Wow, this is amazing Abhilash! So much better than the old wall of text, and so cool that you learned how to write a Sphinx plugin while you were at it.

Cheers, -Barry

On Aug 7, 2020, at 12:31, Abhilash Raj maxking@asynchronous.in wrote:

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)

---

Mailman-Developers mailing list -- mailman-developers@python.org To unsubscribe send an email to mailman-developers-leave@python.org https://mail.python.org/mailman3/lists/mailman-developers.python.org/ Mailman FAQ: https://wiki.list.org/x/AgA3

Security Policy: https://wiki.list.org/x/QIA9