Marginalia 0.9.2

marginalia

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.

<details> <summary>Add this code to the project's `pom.xml` file, and run the command `mvn zi:marginalia`.</summary>

    <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>

</details>

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

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

License

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

Marginalia

Install / Use

README