2011-06-27 14:51:30 +00:00
Marginalia 0.6.0
2010-11-16 03:05:32 +00:00
==========
2011-01-04 15:34:32 +00:00
*ultra-lightweight literate programming[1] for clojure inspired by [docco ](http://jashkenas.github.com/docco/ )*
2010-10-26 18:59:47 +00:00
2011-01-04 15:34:32 +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.
2010-12-21 09:04:49 +00:00
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/ ).
2010-12-21 09:04:49 +00:00
2011-01-04 15:34:32 +00:00
Usage
-----
Currently Marginalia can be used in a number of ways as described below.
### Command Line
2011-06-27 16:50:26 +00:00
You can download the [Marginalia 0.6.0 jar including packaged dependencies from Github ](https://github.com/downloads/fogus/marginalia/marginalia-0.6.0-standalone.jar ).
2011-01-04 15:34:32 +00:00
Running Marginalia given the jar file linked above is as easy as:
2011-06-27 16:50:26 +00:00
java -jar marginalia-0.6.0-standalone.jar
2011-01-04 15:34:32 +00:00
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-06-27 16:50:26 +00:00
java -jar marginalia-0.6.0-standalone.jar < file1 > < file2 > ... < filen >
2011-01-04 15:34:32 +00:00
Arguments can be specific files or directories.
### Leiningen
2011-06-27 14:51:30 +00:00
[http://github.com/fogus/lein-marginalia ](http://github.com/fogus/lein-marginalia )
2011-01-04 15:34:32 +00:00
To use Marginalia in your own projects simply add the following to your `project.clj` file in the `:dev-dependencies` section:
2011-06-28 20:37:44 +00:00
[lein-marginalia "0.6.0"]
2011-01-04 15:34:32 +00:00
After executing `lein deps` you can generate your complete source documentation with the following command:
lein marg
2011-06-27 14:51:30 +00:00
Marginalia accepts other options as outlined in the *Command Line*
section above.
2011-01-04 15:34:32 +00:00
### Cake
2011-06-27 14:51:30 +00:00
[http://github.com/fogus/cake-marginalia ](http://github.com/fogus/cake-marginalia )
2011-06-29 05:56:46 +00:00
Add the following to your project's `:dev-dependencies` :
2011-05-06 02:13:33 +00:00
2011-06-28 20:37:44 +00:00
[cake-marginalia "0.6.0"]
2011-05-06 02:13:33 +00:00
Also, you need to add it to your task list:
2011-06-28 20:37:44 +00:00
:tasks [cake-marginalia.tasks]
Here's a sample `project.clj` :
(defproject my-project "0.1.0
:description "Cake plugin for Marginalia."
:dependencies [[org.clojure/clojure "1.2.1"]
[org.clojure/clojure-contrib "1.2.0"]]
:dev-dependencies [[marginalia "0.6.0"]
[cake-marginalia "0.6.0"]]
:tasks [cake-marginalia.tasks])
2011-05-06 02:13:33 +00:00
After that, you should be able to use it like any other cake task:
cake marg
2011-01-04 15:34:32 +00:00
### Maven
2011-07-15 18:54:32 +00:00
The [zi plugin ](https://github.com/pallet/zi ) supports marginalia.
Add the folowing to your `pom.xml` , and run `mvn zi:marginalia` .
```xml
< plugin >
< groupId > org.cloudhoist.plugin< / groupId >
< artifactId > zi< / artifactId >
< version > 0.3.0< / version >
< configuration >
< marginaliaTargetDirectory > autodoc/marginalia< / marginaliaTargetDirectory >
< / configuration >
< / plugin >
```
And the following to your `settings.xml` .
```xml
< pluginGroups >
< pluginGroup > org.cloudhoist.plugin< / pluginGroup >
< / pluginGroups >
< profiles >
< profile >
< id > clojure-dev< / id >
< pluginRepositories >
< pluginRepository >
< id > sonatype-snapshots< / id >
< url > http://oss.sonatype.org/content/repositories/releases< / url >
< / pluginRepository >
< / pluginRepositories >
< / profile >
< / profiles >
< activeProfiles >
< activeProfile > clojure-dev< / activeProfile >
< / activeProfiles >
```
2011-01-04 15:34:32 +00:00
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.
2010-12-21 09:04:49 +00:00
TODO
----
* paragraph anchors
2011-01-04 15:34:32 +00:00
* options for non-uber-docs
* Maven generation support
* POM parsing
2010-12-21 09:04:49 +00:00
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.
2011-01-04 15:34:32 +00:00
Notes
-----
2011-01-04 15:41:06 +00:00
[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 )
2011-05-11 13:04:19 +00:00
- [Anthony Simpson ](https://github.com/Raynes )
If I've missed your name then please ping me.