Sphinx is a tool that is used to generate documentation from reStructuredText (rST) markup language, and is mainly used in the Python ecosystem. I honor it much for it is a really powerful system, and I have come to appreciate it a lot recently, with my work on documentation of software that falls under the Pylons project.
It is a pity that the markup is not as simple as that of the more popular Markdown, but maybe that was out of necessity, since it is far more advanced: it was initially built as a replacement for the tools that build CPython documentation, which is quite extensive and needs lots of rails.
As an example of that power, have a look at these changes I made for pyramid_tutorials. In that commit, the feature I used allows you to include code snippets directly from files, instead of doing the copy-paste dance, avoiding duplication and rot. This feature is known as literalinclude.
Another feature I recently worked with in the recent past is
intersphinx_mapping. It allows one to generate references in rST as
if those reference were local. For example, if you wanted to generate a
link to the CPython
open() built-in function, you would need only
specify it as
:func:open. This is as opposed to finding the actual
link and specifying it normally.