And now for something completely Pythonic...

Since theming support was introduced in Sphinx 0.6, I’ve seen a few good ones that I’ve subsequently added to the core, and that will be part of Sphinx 1.0.

These themes are (click for larger images):

scrolls, designed by Armin Ronacher, used for Jinja:

agogo, designed by Andi Albrecht, used for sqlparse:

nature, designed by Martin Mahner, used for pip:

haiku, originally designed for the Haiku OS user guide:

My thanks go to all theme designers. I hope that this new selection will lead to increased diversity in Sphinx documentation, and to the development of many new themes in the future!

I know it’s bad behavior, but I’m simply too lazy to do a hg diff before commit, so quite often I committed debugging statements like import pdb; pdb.set_trace() or print foo, left in some module by accident.

Thankfully I’m using Mercurial for most projects now, so it was easy (and fun) to hack up a little extension to “fix” this.

The extension is called hgcodesmell and can be found, as always, on BitBucket. It currently asks you for confirmation when it recognizes any of these smelly changes:

• Debugging helpers left in Python code:
  • print statements
  • pdb.set_trace()
  • 1/0
• vim :q and similar ex commands leaking into the source
• Windows newlines (on non-Windows platforms)

The patterns to recognize are in a simple dictionary mapping from file name glob patterns to a list of (regex, reason) pairs that are checked against all added lines in files that match the respective pattern:

# smelly patterns are tuples (regex, reason)
print_stmt = (re.compile(r'^\+\s*print\b'), 'print statement')
zero_div = (re.compile(r'^\+\s*1/0'), 'zero division error')
set_trace = (re.compile(r'\bpdb\.set_trace\(\)'), 'set_trace')
vim_cmd = (re.compile(r':(w|wq|q|x)$', re.M), 'vim exit command')

# the master dict maps glob patterns to a list of smelly patterns
SMELLY_STUFF = {
    '*.py': [print_stmt, zero_div, set_trace],
    '*': [vim_cmd],
}

It has since saved me quite a few hg rollbacks or worse, commits to fix such stuff, and I think you might find it useful too – get it from here, and please send me any new patterns that are useful for others too!

Reading several reactions to Tarek’s New Year meme suggestion, I saw Sphinx in the first answer of quite a few of them, and that made me very happy. Thanks to you all!

As a result, I feel I should give a short summary of what is up next for Sphinx.

Although it may have seemed that way before Christmas: Unlike Armin, I am not going to switch away from my Python development (I’ve also volunteered for the post of release manager for Python 3.2.x), although it has been slowed by the diploma thesis quite a bit, so progress is not always as fast as I hoped it could be.

These are the next milestones:

• A bugfix release 0.6.4 (with a compatibility fix for the recently released Pygments 1.2)
• A 1.0 beta release containing the domains work
• Bringing the sphinx-web Summer of Code branch up to date and include it at some point

I’ll also write a short post about other news in 1.0 soon.

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.)

Anyway, when domain support is fully implemented, and assuming someone writes a JavaScript domain extension, you will be able to document a JavaScript project (or a mixed project) with Sphinx just as comfortably as you document a Python project right now. Domain-specific objects and rules are used for

• 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 :-)

Please, comment or (preferably) write to sphinx-dev with any wishes, comments or naming suggestions you have. Ah yes, the code is at a BitBucket branch.

"%s" % (obj,)
"%s" % str(obj)

Now, what about this:

"%s %s" % (a, b)
"%s %s" % (str(a), str(b))

It turns out that they aren’t! Given this code:

class Surprise(object):
    def __str__(self):
        return "[str]"
    def __unicode__(self):
        return u"[unicode]"

surprise = Surprise()

print "%s %s" % ("foo", surprise)
print "%s %s" % (u"foo", surprise)

In short, as soon as a Unicode item has been interpolated into a bytestring (which makes the result a Unicode string), further items are automatically use Unicode conversion, given by __unicode__(), if available. This came up recently on the docutils mailing list, where a test failure was triggered because Python 2.6′s IOError has a buggy __unicode__() implementation.