Sphinx domain for Clojure

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?

Yes, I did. There is no mention of how to format the resulting signature. The rendering is done deep in Sphinx (`sphinx.builders.html.py`, `class HTMLTranslator`). It seems you need to write your own HTML builder to render the output. Now, how on earth am I going to document multiple languages in the same project? — André Caron, Apr 20 '11 at 21:24
Did you ever get it working? I'm trying to integrate a clojure project with an existing project using sphinx, but haven't found a sphinx domain for clojure. — user1009908, Aug 03 '14 at 16:46
@user1009908: As explained in [my answer below](http://stackoverflow.com/a/5736906/313063), I tried writing my own extension and could not get anything reasonable to get work because it involved changes to core Sphinx elements which are not accessible to plug-ins. As this was over 3 years ago, maybe things have improved in Sphinx to make this possible. Then again, maybe the Sphinx community has created something better for documenting Clojure code. — André Caron, Aug 03 '14 at 20:29

score 3 · Accepted Answer · answered Apr 20 '11 at 21:32

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.

Sphinx domain for Clojure

1 Answers1