A while back I wanted to run Clojure autodoc on a Maven project using the clojure-maven-plugin. Unfortunately, it was kind of a pain, but not for any good reason.

So, I whipped up an implementation and pushed it up to my fork. Mark has subsequently integrated it into the clojure-maven-plugin directly.

If you’d like to use it yourself and you’re presumably using Maven and the maven-clojure-plugin already, then follow these steps:

1. Document your code. Autodoc just hooks the metadata already (mostly) present in your code – if you’re using docstrings and defn and defmacro, etc then you’re most of the way there already. To add docs for a namespace:

(ns ^{:doc "This is the namespace doc string"} 
  ... )

2. Add an autodoc dependency to your pom. The maven-clojure-plugin does not automatically import this so you’re not tied to it if you don’t want it. Also, you’re not tied to a particular version. Add a dependency like this:

<dependency>
  <groupId>autodoc</groupId>
  <artifactId>autodoc</artifactId>
  <version>0.7.1</version>
  <scope>test</scope>
</dependency>

3. (Optional) Configure the autodoc parameters in the clojure-maven-plugin. By default, the plugin will pull your project description but that can be overridden, along with all the other autodoc properties as follows:

<plugin>
  <groupId>com.theoryinpractise</groupId>
  <artifactId>clojure-maven-plugin</artifactId>
  <version>1.3.6</version>
  <configuration>
    <autodoc>
      <description>Uses ${project.description} by default, but you can override props here</description>
      <copyright>No default for this one</copyright>
      <!-- most other autodoc props will work here -->
    </autodoc>
  </configuration>
</plugin>

4. (Optional) Theme your autodoc. I don’t really know much about this but you can read the autodoc info or look at examples like clojure core or incanter (although I can’t figure out where either of those projects host autodoc stuff). These extra files should go in src/main/autodoc.

5. Run autodoc:

mvn clojure:autodoc

which will put the results in target/autodoc.

Open target/autodoc/index.html and enjoy. If you see things to fix or improve, please fork clojure-maven-plugin and send Mark a pull or a patch!