Marginalia 0.9.2

Marginalia has a new home

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

https://github.com/clj-commons/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.9.2"] to your project.clj's :dev-dependencies argument of the defproject function, then run lein deps.

With Leiningen 2.x, add [[lein-marginalia "0.9.2"]] 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>

deps.edn

Add marginalia/marginalia {:mvn/version "0.9.2"} as a dep. To use it from the command line, do something like this:

{:aliases
  {:marginalia
   {:extra-deps {marginalia/marginalia {:mvn/version "0.9.2"}}
    :main-opts  ["-m" "marginalia.main" "-n" "YourProjectName"
                 "src" "test"]}}}

And invoke it with clojure -M:marginalia. Without the alias, you could use clojure -M -m marginalia.main.

Invocation

Marginalia accepts options as described below:

Flag		Default	Description
-d	--dir	./docs	Directory into which the documentation will be written
-f	--file	uberdoc.html	File into which the documentation will be written
-n	--name	(from project.clj)	Project name
-v	--version	(from project.clj)	Project version
-D	--desc	(from project.clj)	Project description
-a	--deps	(from project.clj)	Project dependencies in the form <group1>:<artifact1>:<version1>;<group2>...
-c	--css	(from project.clj)	Additional css resources <resource1>;<resource2>;...
-j	--js	(from project.clj)	Additional javascript resources <jsfile1>;<jsfile2>;...
-m	--multi	disabled	Generate each namespace documentation as a separate file
-e	--exclude	(from project.clj)	Exclude source file(s) from the document generation process <file1>;<file2>;...
-l	--leiningen		Generate the documentation for a Leiningen project file
-L	--lift-in-line-comments	disabled	Lift ;; inline comments to the top of the enclosing form.
-X	--exclude-lifted-comments	disabled	If inline comments are being lifted, then also exclude them from the source code display

Options can also be added to .marginalia/config.edn (a map with keys taken from the second column of the table).

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.

Marginalia is currently maintained by Tim Macdonald.

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
• Sean Corfield
• Tim Macdonald

If I've missed your name then please ping me.

License

Copyright (C) 2010-2024 Sean Corfield, Gary Deer, Fogus and contributors.

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