Marginalia 1.0.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.

deps.edn

To use Marginalia with deps.edn, add an alias like this:

{:aliases {:docs {:extra-deps {marginalia {:git/url "https://github.com/wactbprot/marginalia"
                                           :sha "1234"}}
                  :exec-fn marginalia.core/-main
                  :main-opts ["-m" "marginalia.core" "-n" "Projectname"]}}}

and run:

clojure -M:docs

Marginalia accepts :main-opts 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)
• -m --multi Generate each namespace documentation as a separate file
• -n --name Project name
• -v --version Project version
• -D --desc Project description
• -a --deps Project dependencies in the form <group1>:<artifact1>:<version1>;<group2>...^☆
• -A --alias ...
• -c --css Additional css resources <resource1>;<resource2>;...
• -j --js Additional javascript resources <jsfile1>;<jsfile2>;...
• -e --exclude Exclude source file(s) from the document generation process <file1>;<file2>;...

^☆ if not given will be taken from project.clj TODO: extract information from deps.edn

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
• Michael Bloom
• Tristan Strange If I've missed your name then please ping me.

License

Copyright (C) 2010-2017 Gary, Fogus and contributors.

Distributed under the Eclipse Public License, the same as Clojure.