Work for #88. First cut at README and release notes doc.
This commit is contained in:
fogus
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/).
|
||||
|
||||
**[View the release notes for this version of Marginalia]()**
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
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
|
||||
|
||||
[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:
|
||||
|
||||
: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:
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
### 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
|
||||
|
||||
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.
|
||||
|
||||
TODO
|
||||
----
|
||||
* paragraph anchors
|
||||
* options for non-uber-docs
|
||||
* Maven generation support
|
||||
* POM parsing
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
Copyright (C) 2010, 2011 Fogus
|
||||
Copyright (C) 2010, 2011 Fogus and contributors.
|
||||
|
||||
Distributed under the Eclipse Public License, the same as Clojure.
|
||||
|
||||
|
|
@ -150,5 +105,6 @@ Marginalia is...
|
|||
- [Vadim](https://github.com/dm3)
|
||||
- [Meikel Brandmeyer](https://github.com/kotarak)
|
||||
- [Paul Dorman](https://github.com/pauldorman)
|
||||
- [Deepak Giridharagopal](https://github.com/grimradical)
|
||||
|
||||
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/)"
|
||||
;; :main marginalia.main
|
||||
:dependencies
|
||||
|
|
|
|||
Loading…
Reference in a new issue