Using Codox Effectively
Codox is a documentation tool for Clojure. It is primarily for API documentation but recent versions allow arbitrary files to be included. This post is a small collection of tips, some of which you may already know. If you are not familiar with Codox, you should probably start with its README.
1. Enable Markdown Globally
Although documenation format can be configured per var, Markdown should just be enabled globally unless you are extending codox with your own pre-processor:
(defproject ...
:codox {:defaults {:doc/format :markdown}}
...)
2. Use h4 for Subheadings
Because var names are displayed with h3’s:
(defn foo
"Summary.
#### Subheading
More info."
...)
3. Add Source Links
(defproject ...
:codox {:src-dir-uri "http://github.com/l33tk1d/fizzbuzz/blob/master/"
:src-linenum-anchor-prefix "L"}
...)
4. Cross Reference All the Things
The reader wants to spend the least time finding relevant documentation:
"Document [[module.submodule/var]]"
Also please make sure all your literals are wrapped with `.
5. Hide Auto-Generated Record Constructors
They just crowd the page. Given MyRecord, ->MyRecord & map->MyRecord is assumed.
(alter-meta! #'->RecordName assoc :no-doc true)
If you have any questions, suggestions or corrections feel free to drop me a line.