The new option is available at the command line with "-e" or "--exclude". It can also be part of the project.clj file via the ":exclude" keyword. I was requiring this feature because I often have local testing files which I don't want to be included in the documentation. The new option is quite simple: it simply filter out the files that have been identified by the option out of the "sources" var before it is being used by multidoc! or uberdoc!
5.3 KiB
Marginalia 0.8.0
Ultra-lightweight literate programming[1] for Clojure and ClojureScript inspired by docco
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.
To get a quick look at what the Marginalia output looks like, visit the official site.
View the release notes for this version of Marginalia
Usage
Currently Marginalia can be used in a number of ways as described below.
Leiningen
http://github.com/gdeer81/lein-marginalia
To use Marginalia with Leiningen add the following code to the project's project.clj
file:
With Leiningen 1.x, add [lein-marginalia "0.8.0"]
to your project.clj's :dev-dependencies
argument of the defproject
function, then run lein deps
.
With Leiningen 2.x, add [[lein-marginalia "0.8.0"]]
to the :plugins
entry in either your project.clj file or your :user
profile.
See the lein-marginalia page for more details.
Once installed, you can generate your complete source documentation with the command:
lein marg <options> <files>
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 fromproject.clj
) - -c --css Additional css resources
<resource1>;<resource2>;...
(if not given will be taken fromproject.clj
) - -j --js Additional javascript resources
<jsfile1>;<jsfile2>;...
(if not given will be taken fromproject.clj
) - -m --multi Generate each namespace documentation as a separate file
- -e --exclude Exclude source file(s) from the document generation process
<file1>;<file2>;...
(if not given will be taken fromproject.clj
)
Maven
The zi plugin supports Marginalia.
Add this code to the project's pom.xml
file, and run the command mvn zi:marginalia
.
<plugin>
<groupId>org.cloudhoist.plugin</groupId>
<artifactId>zi</artifactId>
<version>0.5.0</version>
<configuration>
<marginaliaTargetDirectory>autodoc/marginalia</marginaliaTargetDirectory>
</configuration>
</plugin>
And the following to the project's settings.xml
file.
<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>
Contributors and thanks
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.
I would also like to thank Justin Balthrop and Brenton Ashworth for their support and code contributions.
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.
Marginalia is...
sorted by first commit
- Fogus
- Zachary Kim
- Justin Balthrop
- Brenton Ashworth
- Nicolas Buduroi
- Michael Harrison
- Anthony Grimes
- Sam Ritchie
- Hugo Duncan
- Vadim
- Meikel Brandmeyer
- Paul Dorman
- Deepak Giridharagopal
- Tero Parviainen
- MerelyAPseudonym
- Ivan
- benjamin bader
- Frederick Giasson
If I've missed your name then please ping me.
License
Copyright (C) 2010-2013 Fogus and contributors.
Distributed under the Eclipse Public License, the same as Clojure.