marginalia/README.md

85 lines
2.7 KiB
Markdown
Raw Normal View History

2010-11-16 03:05:32 +00:00
Marginalia
==========
*ultra-lightweight literate programming[1] for clojure inspired by [docco](http://jashkenas.github.com/docco/)*
2010-10-26 18:59:47 +00:00
Marginalia is a source documentation too that parses Clojure code and outputs an side-by-side source view with appropriate comments and docstrings aligned.
2011-01-25 16:52:11 +00:00
To get a quick look at what marginalia output looks like, then [visit the official site](http://fogus.me/fun/marginalia/).
Usage
-----
Currently Marginalia can be used in a number of ways as described below.
### Command Line
2011-02-24 15:40:56 +00:00
You can download the [Marginalia 0.5.0 jar including packaged dependencies from Github](https://github.com/downloads/fogus/marginalia/marginalia-0.5.0-standalone.jar).
Running Marginalia given the jar file linked above is as easy as:
2011-02-24 15:40:56 +00:00
java -jar marginalia-0.5.0-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:
2011-02-24 15:40:56 +00:00
java -jar marginalia-0.5.0-standalone.jar <file1> <file2> ... <filen>
Arguments can be specific files or directories.
### Leiningen
To use Marginalia in your own projects simply add the following to your `project.clj` file in the `:dev-dependencies` section:
2011-02-24 15:40:56 +00:00
[marginalia "0.5.0"]
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.
### Cake
TBD
### Maven
Not yet supported.
Contributors and thanks
-----------------------
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.
TODO
----
* paragraph anchors
* options for non-uber-docs
* Maven generation support
* POM parsing
2010-11-16 03:05:32 +00:00
License
-------
2010-10-26 18:59:47 +00:00
2010-11-16 03:05:32 +00:00
Copyright (C) 2010 Fogus
2010-10-26 18:59:47 +00:00
Distributed under the Eclipse Public License, the same as Clojure.
Notes
-----
[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.
2011-03-02 01:55:22 +00:00
Marginalia is...
----------------
*sorted by first commit*
- [Fogus](http://fogus.me/fun/)
- [Zachary Kim](https://github.com/zkim)
- [Justin Balthrop](https://github.com/ninjudd)
- [Brenton Ashworth](https://github.com/brentonashworth)
- [Nicolas Buduroi](https://github.com/budu)
- [Michael Harrison](https://github.com/goodmike)