New in Sphinx 1.0: Domains
So I’ll write a bit about an exciting new feature of Sphinx 1.0, the upcoming release (no, don’t hold your breath).
As you may know, Sphinx started out as a “proprietary” tool used exclusively for building the Python documentation after the switch to reStructuredText for markup. When I decided to make it available for public use, I had to remove quite a lot of Python-specific stuff (and I keep finding small such items even today). But still, Sphinx is very centered on documentation of Python code: Its most fundamental directives, like the class directive, document a Python object. The naming and argument parsing is Python-specific, there is a module index of all Python modules you documented, you can link to other Python objects via intersphinx, etc. But there was already support for documenting C stuff (since the Python/C API was also part of the original documentation), and I know people also document C++. Even the Sphinx docs themselves abuse the Python object markup for HTML template elements.
Exactly that class directive was what triggered a step away from the Python-centric viewpoint: in my naive happiness about how neat .. class:: Foo looks, I overlooked docutils’ own directive of that name. Later I tried to correct this, by exporting the latter as cssclass which doesn’t do it justice though. The thread on the mailing list brought up the possibility to “namespace” directives, and that was the starting point. Finally, at EuroPython, Armin and myself came up with the concept of “domains”.
A domain is a collection of markup to describe and link to “objects” belonging together, e.g. elements of a programming language. Directive and role names are of the form domain:name.
Of course, there is a way to set a “default domain” so that you can continue writing .. function:: foo() instead of the more verbose .. py:function:: foo(). (The name “domain” is awkward, but “language” is already taken for “the language the docs are written in” and anyway doesn’t cover the full possible range of domain usage. Other terms like “group” or “context” don’t feel better.)
- obviously, directives to document objects
- resolving references to these objects via roles
- the search function (it currently lists matching Python objects first)
- the inventory for intersphinx
- the global module index (I’m still unsure how to do that, though)
Extension authors will loathe me for this, because I not only broke lots of (internal) interfaces, but also took the opportunity to refactor a few other spots that always bugged me. I do however offer help porting extensions to anyone, once the release is out. I really think this step was necessary for Sphinx to look ahead into a bright future :-)