Question

I’m used to working with Sphinx for C++ and Python projects. I’ve just started a project in Clojure and I’d like to re-use my Sphinx/reStructuredText skills to document my Clojure code. Since there’s no built-in domain for Clojure, I started writing one.

Ironically, Sphinx’s documentation is of no help at all for writing extensions. So, starting from the built-in modes for Python and Javascript, I’ve got some basic elements working. I can write document for functions using the following directives:

.. clj:ns:: clojure.core

.. clj:fn:: (filter f coll)

   :param f: predicate
   :param coll: collection

   Built-in!

However, the HTML output produces C/Python-style signatures. The preceding example generates something like this:

filter(f, coll)

    Parameters: * f - predicate
                * coll - collection

    Built-in!

I’d much rather get the signature in the lisp-ish form as:

(filter f coll)

    Parameters: * f - predicate
                * coll - collection

    Built-in!

The code that generates the signatures seems to go all the way down to docutils.addnodes module. How can I make Sphinx generate the HTML using the Sphinx syntax? Can it be done with a template, or do I need hack my way through the whole builder system to do this?

Answer 1

As of the current version (1.0.7), changing how the signature is formatted involves extending the HTMLTranslator class in Sphinx (sphinx/writers/html.py). However, there is no domain-specific handling at this level, changes for Clojure signatures will affect signatures on other domains too.