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 <maxk...@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/mailman/config/docs/config.html#configuration-options > ((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-le...@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
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ Mailman-Developers mailing list -- mailman-developers@python.org To unsubscribe send an email to mailman-developers-le...@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
