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 extension开发者_如何学Gos. 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?
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.
精彩评论