2014-08-29 02:47:01 +00:00
Marginalia 0.8.0
2012-03-06 16:46:18 +00:00
================
2013-08-13 12:56:51 +00:00
**[Marginalia has a new home](http://blog.fogus.me/2013/08/12/marginalia-has-a-new-home/)**
2013-08-07 13:07:31 +00:00
2012-06-08 15:31:59 +00:00
![marginalia ](http://farm8.staticflickr.com/7057/6828224448_32b51e5784_z_d.jpg "Marginalia" )
2012-03-06 16:46:18 +00:00
2012-06-08 15:30:10 +00:00
*Ultra-lightweight literate programming[1] for [Clojure ](http://clojure.org ) and ClojureScript inspired by [docco ](http://jashkenas.github.com/docco/ )*
2010-10-26 18:59:47 +00:00
2013-05-30 12:52:21 +00:00
Marginalia is a source code documentation tool that parses Clojure and ClojureScript code and outputs a side-by-side source view with appropriate comments and docstrings aligned.
2010-12-21 09:04:49 +00:00
2013-09-18 08:54:58 +00:00
To get a quick look at what the Marginalia output looks like, [visit the official site ](http://gdeer81.github.io/marginalia/ ).
2010-12-21 09:04:49 +00:00
2014-03-01 03:40:09 +00:00
**[View the release notes for this version of Marginalia](https://github.com/gdeer81/marginalia/blob/master/docs/release-notes/marginalia-v0.7.1-release-notes.markdown)**
2012-03-06 18:00:28 +00:00
2011-01-04 15:34:32 +00:00
Usage
-----
Currently Marginalia can be used in a number of ways as described below.
### Leiningen
2013-10-13 18:16:27 +00:00
[http://github.com/gdeer81/lein-marginalia ](http://github.com/gdeer81/lein-marginalia )
2011-06-27 14:51:30 +00:00
2013-05-23 02:51:52 +00:00
To use Marginalia with Leiningen add the following code to the project's `project.clj` file:
2011-01-04 15:34:32 +00:00
2013-05-23 02:51:52 +00:00
With Leiningen 1.x, add `[lein-marginalia "0.7.1"]` to your project.clj's `:dev-dependencies` argument of the `defproject` function, then run `lein deps` .
With Leiningen 2.x, add `[[lein-marginalia "0.7.1"]]` to the `:plugins` entry in either your project.clj file or your `:user` profile.
2013-10-13 18:16:27 +00:00
See the [lein-marginalia ](http://github.com/gdeer81/lein-marginalia ) page for more details.
2011-01-04 15:34:32 +00:00
2013-05-23 02:51:52 +00:00
Once installed, you can generate your complete source documentation with the command:
2011-01-04 15:34:32 +00:00
2012-06-08 15:30:10 +00:00
lein marg < options > < files >
2011-01-04 15:34:32 +00:00
2012-06-08 15:30:10 +00:00
Marginalia accepts options as described below:
* -d --dir Directory into which the documentation will be written (default `docs` )
* -f --file File into which the documentation will be written (default `uberdoc.html` )
* -n --name Project name (if not given will be taken from `project.clj` )
* -v --version Project version (if not given will be taken from `project.clj` )
* -D --desc Project description (if not given will be taken from `project.clj` )
* -a --deps Project dependencies in the form `<group1>:<artifact1>:<version1>;<group2>...` (if not given will be taken from `project.clj` )
* -c --css Additional css resources `<resource1>;<resource2>;...` (if not given will be taken from `project.clj` )
* -j --js Additional javascript resources `<jsfile1>;<jsfile2>;...` (if not given will be taken from `project.clj` )
* -m --multi Generate each namespace documentation as a separate file
2011-01-04 15:34:32 +00:00
### Maven
2011-10-06 05:06:51 +00:00
The [zi plugin ](https://github.com/pallet/zi ) supports Marginalia.
2011-07-15 18:54:32 +00:00
2011-10-06 05:06:51 +00:00
Add this code to the project's `pom.xml` file, and run the command `mvn zi:marginalia` .
2011-07-15 18:54:32 +00:00
```xml
< plugin >
< groupId > org.cloudhoist.plugin< / groupId >
< artifactId > zi< / artifactId >
2012-06-08 15:33:53 +00:00
< version > 0.5.0< / version >
2011-07-15 18:54:32 +00:00
< configuration >
< marginaliaTargetDirectory > autodoc/marginalia< / marginaliaTargetDirectory >
< / configuration >
< / plugin >
```
2011-10-06 05:06:51 +00:00
And the following to the project's `settings.xml` file.
2011-07-15 18:54:32 +00:00
```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
-----------------------
2011-10-06 05:06:51 +00:00
I would like to thank Zachary Kim for taking a pile of incoherent code and making it something worth using. Marginalia would be nothing without his hard work and vision.
2011-01-04 15:34:32 +00:00
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
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
2013-05-30 12:52:21 +00:00
Marginalia is...
2011-03-02 01:55:22 +00:00
----------------
*sorted by first commit*
- [Fogus ](http://fogus.me/fun/ )
2013-10-13 18:16:27 +00:00
- [Zachary Kim ](https://github.com/zk )
2011-03-02 01:55:22 +00:00
- [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-07-18 20:17:03 +00:00
- [Anthony Grimes ](https://github.com/Raynes )
2013-10-13 18:16:27 +00:00
- [Sam Ritchie ](https://github.com/sritchie )
2011-07-16 14:35:05 +00:00
- [Hugo Duncan ](https://github.com/hugoduncan )
2011-08-10 12:35:54 +00:00
- [Vadim ](https://github.com/dm3 )
2011-09-07 01:13:04 +00:00
- [Meikel Brandmeyer ](https://github.com/kotarak )
2011-10-06 12:18:45 +00:00
- [Paul Dorman ](https://github.com/pauldorman )
2012-03-06 18:00:28 +00:00
- [Deepak Giridharagopal ](https://github.com/grimradical )
2012-04-12 18:59:11 +00:00
- [Tero Parviainen ](https://github.com/teropa )
2013-05-22 12:48:49 +00:00
- [MerelyAPseudonym ](https://github.com/MerelyAPseudonym )
- [Ivan ](https://github.com/ivantm )
2014-02-22 01:10:48 +00:00
- [benjamin bader] (https://github.com/benjamin-bader)
2011-05-11 13:04:19 +00:00
If I've missed your name then please ping me.
2013-05-30 12:52:21 +00:00
License
-------
Copyright (C) 2010-2013 Fogus and contributors.
Distributed under the Eclipse Public License, the same as Clojure.