Style Guide for Writing Sphinx Extensions

[mmcky]

The documentation for writing sphinx extensions can be confusing and incomplete. It would be nice to put together a style guide that captures some of the learning from the ebp project so that others can use it (or possibly upstream to Sphinx).

I think there is scope to write both a tutorial and reference elements to the documentation:

• tutorial for writing an extension for jupyter-book for custom admonitions
• more details on the overall execution model of sphinx (init, parsing, transforms, post_tranforms, translators)

Other Topics:

• how cross referencing works in sphinx
• adding compatibility with ref and numref via labels

[choldgraf]

Im a big fan of minimal reproducible examples. Could we define the 4-5 most common ways to extend Sphinx, and document a minimal reproducible examples for each? That could be useful to copy paste as well as teach