Work for #88. First cut at README and release notes doc.
This commit is contained in:
parent
660e640f6c
commit
dcaa66116b
3 changed files with 73 additions and 50 deletions
54
README.md
54
README.md
|
@ -7,32 +7,20 @@ Marginalia is a source code documentation tool that parses Clojure code and outp
|
||||||
|
|
||||||
To get a quick look at what marginalia output looks like, [visit the official site](http://fogus.me/fun/marginalia/).
|
To get a quick look at what marginalia output looks like, [visit the official site](http://fogus.me/fun/marginalia/).
|
||||||
|
|
||||||
|
**[View the release notes for this version of Marginalia]()**
|
||||||
|
|
||||||
Usage
|
Usage
|
||||||
-----
|
-----
|
||||||
|
|
||||||
Currently Marginalia can be used in a number of ways as described below.
|
Currently Marginalia can be used in a number of ways as described below.
|
||||||
|
|
||||||
### Command Line
|
|
||||||
|
|
||||||
You can download the [Marginalia 0.6.1 jar including packaged dependencies from Github](https://github.com/downloads/fogus/marginalia/marginalia-0.6.1-standalone.jar).
|
|
||||||
|
|
||||||
Running Marginalia given the jar file linked above is as easy as:
|
|
||||||
|
|
||||||
java -jar marginalia-0.6.1-standalone.jar
|
|
||||||
|
|
||||||
This will search the `$PWD` (current working directory) for a `src` directory, which it will then traverse looking for Clojure source files to generate documentation for. Marginalia can also take specified directories and/or files for which to generate documentation:
|
|
||||||
|
|
||||||
java -jar marginalia-0.6.1-standalone.jar <path1> <path2> ... <pathn>
|
|
||||||
|
|
||||||
Path arguments may refer to files or directories.
|
|
||||||
|
|
||||||
### Leiningen
|
### Leiningen
|
||||||
|
|
||||||
[http://github.com/fogus/lein-marginalia](http://github.com/fogus/lein-marginalia)
|
[http://github.com/fogus/lein-marginalia](http://github.com/fogus/lein-marginalia)
|
||||||
|
|
||||||
To use Marginalia with Leiningen add the following code to the project's `project.clj` file, in the `:dev-dependencies` argument of the `defproject` function:
|
To use Marginalia with Leiningen add the following code to the project's `project.clj` file, in the `:dev-dependencies` argument of the `defproject` function:
|
||||||
|
|
||||||
:dev-dependencies [lein-marginalia "0.6.0"]
|
:dev-dependencies [lein-marginalia "0.7.0"]
|
||||||
|
|
||||||
After executing `lein deps` you can generate your complete source documentation with the command:
|
After executing `lein deps` you can generate your complete source documentation with the command:
|
||||||
|
|
||||||
|
@ -40,32 +28,6 @@ After executing `lein deps` you can generate your complete source documentation
|
||||||
|
|
||||||
Marginalia accepts other options as described in the *Command Line* section above.
|
Marginalia accepts other options as described in the *Command Line* section above.
|
||||||
|
|
||||||
### Cake
|
|
||||||
|
|
||||||
[http://github.com/fogus/cake-marginalia](http://github.com/fogus/cake-marginalia)
|
|
||||||
|
|
||||||
To use Marginalia with Cake add the following code to the project's `project.clj` file, in the `:dev-dependencies` argument of the `defproject` function:
|
|
||||||
|
|
||||||
:dev-dependencies [cake-marginalia "0.6.0"]
|
|
||||||
|
|
||||||
Also, you need add this code to the `:tasks` argument for the `defproject` function:
|
|
||||||
|
|
||||||
:tasks [cake-marginalia.tasks]
|
|
||||||
|
|
||||||
Here's an example `project.clj` file:
|
|
||||||
|
|
||||||
(defproject my-project "0.1.0
|
|
||||||
:description "Cake plugin for Marginalia."
|
|
||||||
:dependencies [[org.clojure/clojure "1.2.1"]
|
|
||||||
[org.clojure/clojure-contrib "1.2.0"]]
|
|
||||||
:dev-dependencies [[marginalia "0.6.1"]
|
|
||||||
[cake-marginalia "0.6.0"]]
|
|
||||||
:tasks [cake-marginalia.tasks])
|
|
||||||
|
|
||||||
Marginalia is called like any other Cake task:
|
|
||||||
|
|
||||||
cake marg
|
|
||||||
|
|
||||||
### Maven
|
### Maven
|
||||||
|
|
||||||
The [zi plugin](https://github.com/pallet/zi) supports Marginalia.
|
The [zi plugin](https://github.com/pallet/zi) supports Marginalia.
|
||||||
|
@ -114,17 +76,10 @@ I would like to thank Zachary Kim for taking a pile of incoherent code and makin
|
||||||
|
|
||||||
I would also like to thank Justin Balthrop and Brenton Ashworth for their support and code contributions.
|
I would also like to thank Justin Balthrop and Brenton Ashworth for their support and code contributions.
|
||||||
|
|
||||||
TODO
|
|
||||||
----
|
|
||||||
* paragraph anchors
|
|
||||||
* options for non-uber-docs
|
|
||||||
* Maven generation support
|
|
||||||
* POM parsing
|
|
||||||
|
|
||||||
License
|
License
|
||||||
-------
|
-------
|
||||||
|
|
||||||
Copyright (C) 2010, 2011 Fogus
|
Copyright (C) 2010, 2011 Fogus and contributors.
|
||||||
|
|
||||||
Distributed under the Eclipse Public License, the same as Clojure.
|
Distributed under the Eclipse Public License, the same as Clojure.
|
||||||
|
|
||||||
|
@ -150,5 +105,6 @@ Marginalia is...
|
||||||
- [Vadim](https://github.com/dm3)
|
- [Vadim](https://github.com/dm3)
|
||||||
- [Meikel Brandmeyer](https://github.com/kotarak)
|
- [Meikel Brandmeyer](https://github.com/kotarak)
|
||||||
- [Paul Dorman](https://github.com/pauldorman)
|
- [Paul Dorman](https://github.com/pauldorman)
|
||||||
|
- [Deepak Giridharagopal](https://github.com/grimradical)
|
||||||
|
|
||||||
If I've missed your name then please ping me.
|
If I've missed your name then please ping me.
|
||||||
|
|
67
docs/release-notes/marginalia-v0.7.0-release-notes.markdown
Normal file
67
docs/release-notes/marginalia-v0.7.0-release-notes.markdown
Normal file
|
@ -0,0 +1,67 @@
|
||||||
|
Marginalia v0.7.0 Release Notes
|
||||||
|
===============================
|
||||||
|
|
||||||
|
Marginalia is an ultra-lightweight literate programming tool for Clojure inspired by [docco](http://jashkenas.github.com/docco/)*.
|
||||||
|
|
||||||
|
To get a quick look at what the output looks like, [visit the official Marginalia website](http://fogus.me/fun/marginalia/).
|
||||||
|
|
||||||
|
**Usage notes and examples are found on the [Marginalia Github page](http://github.com/fogus/marginalia).**
|
||||||
|
|
||||||
|
Places
|
||||||
|
------
|
||||||
|
|
||||||
|
* [Source code](https://github.com/fogus/marginalia)
|
||||||
|
* [Ticket system](https://github.com/fogus/marginalia/issues)
|
||||||
|
* [manifesto](http://blog.fogus.me/2011/01/05/the-marginalia-manifesto/)
|
||||||
|
|
||||||
|
Changes from v6.0.1
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
### lein-marginalia
|
||||||
|
|
||||||
|
Version 0.7.0 is an attempt to move toward Marginalia as library only. Therefore, the Leiningen support has been pulled out and placed into its own plugin named [lein-marginalia](http://github.com/fogus/lein-marginalia). To use Marginalia to generate documentation for your own projects you should no longer reference Marginalia in your `project.clj`. Instead, use lein-marginalia in your `:dev-dependencies` section like so:
|
||||||
|
|
||||||
|
:dev-dependencies [[lein-marginalia "0.7.0"]]
|
||||||
|
|
||||||
|
Leiningen will pull in the proper Marginalia version. We will attempt to keep the version numbers in sync.
|
||||||
|
|
||||||
|
### ClojureScript support
|
||||||
|
|
||||||
|
Marginalia will now discover and parse ClojureScript files.
|
||||||
|
|
||||||
|
### def docstrings
|
||||||
|
|
||||||
|
Clojure 1.3 allows docstrings in `def` forms that look like:
|
||||||
|
|
||||||
|
(def a-var value "The docstring")
|
||||||
|
|
||||||
|
Marginalia will recognize this pattern and generate the associate documentation.
|
||||||
|
|
||||||
|
### Wildcard arguments
|
||||||
|
|
||||||
|
Marginalia will accept wildcard arguments in place of absolute source paths. For example, to generate docs for all source files with an 'r' in the name, you could type:
|
||||||
|
|
||||||
|
lein marg src/**/*r*.clj
|
||||||
|
|
||||||
|
You can pass any number of arguments to the `marg` task.
|
||||||
|
|
||||||
|
### Bug fixes
|
||||||
|
|
||||||
|
* Prefixed keywords (#54 and #87)
|
||||||
|
* [`project.clj` requirement](https://github.com/fogus/marginalia/issues/20)
|
||||||
|
* [`^:private support`](https://github.com/fogus/marginalia/issues/49)
|
||||||
|
* [Comment code blocks](https://github.com/fogus/marginalia/issues/50)
|
||||||
|
* [`:requires` bug](https://github.com/fogus/marginalia/issues/55)
|
||||||
|
|
||||||
|
|
||||||
|
Plans
|
||||||
|
-----
|
||||||
|
|
||||||
|
The following capabilities are under design, development, or consideration for future versions of Marginalia:
|
||||||
|
|
||||||
|
* protocol docstring support
|
||||||
|
* Stand-alone application
|
||||||
|
* Explore the possibility of leveraging the [ClojureScript](http://github.com/clojure/clojurescript) analyzer.
|
||||||
|
* More documentation and examples
|
||||||
|
|
||||||
|
More planning is needed around capabilities not listed nor thought of.
|
|
@ -1,4 +1,4 @@
|
||||||
(defproject marginalia "0.7.0-SNAPSHOT"
|
(defproject marginalia "0.7.0"
|
||||||
:description "lightweight literate programming for clojure -- inspired by [docco](http://jashkenas.github.com/docco/)"
|
:description "lightweight literate programming for clojure -- inspired by [docco](http://jashkenas.github.com/docco/)"
|
||||||
;; :main marginalia.main
|
;; :main marginalia.main
|
||||||
:dependencies
|
:dependencies
|
||||||
|
|
Loading…
Reference in a new issue