Add mechanism for side-by-side comparison of setup.py and its equivalent setup.cfg

[pganssle]

We have many documentation examples that are purely declarative and are either documented as setup.py or setup.cfg. It would be really awesome if, for each of these, we had the option to have either both versions side-by-side or, even better, in a sort of "tabbed container", like the one in the code sample at the bottom of this example.

Requirements for this:

1. Cannot link to any third-party javascript dependencies. Ideally we wouldn't use any at all, but if you do they must be vendored in the documentation.
2. If javascript is disabled, it has to fall back to something intelligible.

Ideally it would be implemented in pure CSS / HTML if that's at all possible.

[alvyjudy]

Hi I'm just wondering if this is for setuptools' own documentation? because if it is built with sphinx I would think this is about making a sphinx extension that generates such tabbed container ?

[jaraco]

Yes, this probably would be for Setuptools' own documentation. Perhaps Sphinx would need to have an extension, or perhaps there's another approach that would suffice (embedded HTML/JS, ...). I've also experienced the constraining environment of Sphinx when all I wanted to do was provide URLs with substitutions using Sphinx variables (settled on it's not possible). I'm open to innovations that achieve the objective.

[amy-lei]

I'll look into this!

Seems like there exists a sphinx-extension that implements the tabbed container if we go that route. However, it does use JS to achieve this and doesn't account for when JS is disabled (requirement#2).

I'm thinking about exploring embedded HTML/CSS (and have it be side-by-side like a responsive flexbox) or create a similar tab extension that will account for when JS is disabled.