Coverage.py reads settings from a number of different files, in either INI-file or TOML syntax, with different section headings depending on the file. This could be confusing: the docs showed the syntax needed for .coveragerc, but if you were using one of the other files, you had to mentally convert from one syntax to another.
To make it easier, I updated the documentation to show all the syntax possibilities when showing examples of configuration files. I used sphinx-code-tabs to create tabbed code sections.
The result looks like this: a three-tabbed code box. The tabs have the names of configuration files. Selecting a tab shows the syntax you need for that particular file:
Originally I wanted to write the settings just once, and use cog to run Python code to convert from INI syntax to TOML.
If you haven’t seen cog before, it lets you insert small chunks of Python into static files. The Python code is executed to generate more static content that appears alongside the Python code. It’s a simple tool that works well when you have a mostly static file, but you want part of it to be computed.
But I sensed that converting between syntaxes be difficult, especially since some of my examples (as the ones above) have comments in them.
So I went with a simpler approach: the Python snippets in the doc files have both INI and TOML chunks. The INI chunk is lightly massaged to make two of the tabs, since they only differ in the section names. To ensure the two input chunks are in sync, the code reads the configuration examples, and checks that the INI and TOML chunks create the same settings values.
This guarantees that the different syntaxes are all valid, both as generic INI or TOML, but also as coverage.py settings. And it guarantees that the two chunks show the same settings, differing only in syntax.
It’s a little bulky in the resulting .rst files, but it provides the reader with the information they need, and it keeps me from making mistakes.