State of the Art for Clojure Documentation Tools [closed]

Answer 1

Autodoc is an easy place to start and is what Clojure core and Clojure contrib produce.

Easy to use with Maven. I'm not sure if plugins exist for Leiningen or Cake.

Answer 2

I really like Marginalia if you want to take something like a literate programming approach. Marginalia traverses your source code, and produces an html formatted version with comments set beside code in a very clear text. Comments can be markdown formatted, making for a very readable final document. When reviewing source code that I've written some time ago, I find Marginalia really helps. Here's an example made from the Marginalia source itself.

Note that this differs from the original literate programming workflow, where you would write a file and source code is generated from that. With Marginalia, you write a regular source code file, and it's the documentation that's pulled out of that. The output is similar to what one might expect from literate programming, but this way you can still expect syntax highlighting in an editor, without any special literate programming support.

It interoperates with Leiningen, and I believe cake, though I haven't tried that myself.

Answer 3

If you want to go fully literate you should give org-babel-clojure a look. org-bable is a literate programming extension to the emacs org-mode.

If you want to use nrepl the following should be added to your .emacs:

(defun org-babel-execute:clojure (body params)
  "Execute a block of Clojure code with Babel."
  (let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns))
        (result-type  (cdr (assoc :result-type params))))
    (org-babel-script-escape
     (cond ((eq result-type 'value)  (plist-get result-plist :value))
           ((eq result-type 'output) (plist-get result-plist :value))
            (t                        (message "Unknown :results type!"))))))

Answer 4

Codox is a more recent documentation generator for Clojure.