ultra-lightweight literate programming[1] for clojure inspired by docco
Marginalia is a source documentation too that parses Clojure code and outputs an side-by-side source view with appropriate comments and docstrings aligned.
To get a quick look at what marginalia output looks like, then visit the official site.
Currently Marginalia can be used in a number of ways as described below.
You can download the Marginalia 0.3.2 jar including packaged dependencies from Github.
Running Marginalia given the jar file linked above is as easy as:
java -jar marginalia-0.3.2-standalone.jar
This will search the PWD for a src directory which it will then traverse looking for Clojure source files to parse and generate documentation for. Marginalia also takes specific locations and files to generate docs for:
java -jar marginalia-0.3.2-standalone.jar <file1> <file2> ... <filen>
Arguments can be specific files or directories.
To use Marginalia in your own projects simply add the following to your project.clj file in the :dev-dependencies section:
[marginalia "0.3.2"]
After executing lein deps you can generate your complete source documentation with the following command:
lein marg
Marginalia accepts other options as outlined in the Command Line section above.
TBD
Not yet supported.
I would like to thank Zachary Kim for taking a pile of incoherant code and making it something worth using. Marginalia would be nothing without his hard work and vision.
I would also like to thank Justin Balthrop and Brenton Ashworth for their support and code contributions.
- paragraph anchors
- options for non-uber-docs
- Maven generation support
- POM parsing
Copyright (C) 2010 Fogus
Distributed under the Eclipse Public License, the same as Clojure.
[1] While the phrase ultra-lightweight literate programming is used to describe Marginalia, it is in no way a tool for classical literate programming. That is, Marginalia is a linear documentation generator allowing no out-of-order reassembly of source.