I initially planned to file a simple patch but it grew into a full-fledged extension so the commit history is pretty meaningless now. Behind the scenes it still took about five iterations to get this Done Right.
I started off with writing a new builder from scratch which was a nice exercise for the i18n builder I am going to write but overachieving in terms of this simple extension. It was a pretty braindead implementation and used close to zero of Sphinx’s Builder API. I glimpsed briefly into inheriting from StandaloneHTMLBuilder — the HTML document builder — which was a little obtuse and clumsy for creating just a hand full of generic documents. With discovering the intricacies of the build process I learned how to hook into the right places and use existing build features (such as status iterators, which render a handy progressbar during the build).
It then hit me that the extension mechanism might well be a better entry point for my plugin and so it was. An initial version created all documents in isolation of the original build process which was okay but would’ve required a time machine for integrating the sidebar extension into existing pages, which struck me as an odd and overly heavy dependency. I quickly split up the (already two-pass) build process into a collection and a build phase and could easily insert links to the sidebar panels into original documents.
- Pocoo’s already using Mercurial. Developing features, as minor as they may seem, should happen in a fork, not a checkout-patch (which I’m still used to from Python SVN).
- Sphinx’ documentation needs update in the “Writing a new builder” chapter. I will perhaps come around to that while writing/documenting my next builder.
- Review is awesome and does not need an extensive toolchain. Georg Brandl briefly discussed the extension (by loading and trying it himself); his comments allowed me to fill in gaps in the documentation.
- Docutils perhaps has a few bugs in trunk that interfered during debugging. (See #2993967 and r6293/#2993967).