tychoish, a wiki

tychoish/rhizome/ Sphinx Caveats

Sphinx Caveats

8 February 2013

This is a rough sketch of some things that I've learned about the Sphinx documentation generation system. I should probably spend some time to collect what I've learned in a more coherent and durable format, but this will have to do for now:

Sphinx is great. Even though I'm always looking at different documentation systems and practices I can't find anything that's better. My hope is that the more I/we talk about these issues and the closer I/we'll get to solutions, and the better the solutions will be.

Onward and Upward!

  1. In Python this isn't a real problem, but reStructuredText describes a basically XML-like document, and some structures like headings are not easy to embed in rst blocks. ↩

  2. In reality documentation sets would need to be many hundreds of thousands of words for this to actually matter in a significant way. I've seen documentation take 2-3 minutes for clean a regeneration using Sphinx on very powerful hardware (SSDs, contemporary server-grade processors, etc.), and while this shouldn't be a deal breaker for anyone, documentation that's slow to regenerate is harder to maintain and keep up to date (e.g. difficult to test the effect of changes on output, non-trivial to update the documents regularly with small fixes.) ↩