IcedDoc
=========

An API documentation generator for CoffeeScript
-----------------------------------------------

IcedDoc is a simple API documentation generator for [IcedCoffeeScript][]. It reads
python-style docstrings in your CoffeeScript class and function definitions,
passes them through [Markdown][] and outputs the result as easy to read HTML.

Thanks to apgwoz, IcedDoc can also generate wiki
pages for Github!

IcedDoc can also return your documentation as JSON, so you can run it through
an external documentation system such as [Sphinx][].

IcedDoc is inspired by the excellent [Docco][], and is intended for projects
that require more structured API documentation.

The docstring convention IcedDoc uses is inspired by Python, and looks like
this:

``coffeescript ###

`IcedDoc example documentation #`

This is a module-level docstring, and will be displayed at the top of the module documentation. Documentation generated by IcedDoc ###

class MyClass extends Superclass ### This docstring documents MyClass. It can include Markdown syntax, which will be converted to html. ### constructor: (@args) -> ### Constructor documentation goes here. ###

method: (args) -> ### This is a method of MyClass ###

myFunc = (arg1, arg2, args...) -> ### This function will be documented by IcedDoc ### doSomething()`

The documentation generated from the above script can be seen here. For a more interesting example, here is the result of running iceddoc againstsrc/iceddoc.coffee.

`$3`

IcedDoc requires [Node.js][], [IcedCoffeeScript][], [eco][], and [optimist][]. Install using npm with the following command:

sudo npm install -g iceddoc

The -g option installs IcedDoc globally, adding the iceddoc executable to your PATH. If you would rather install locally, omit the -g option.

You can also install from source using cake. From the source directory, run:

sudo cake install

`$3`

IcedDoc can be run from the command line:

Usage: iceddoc [options] [targets]

Options: --output, -o Set output directory [default: "docs"] --parser Parser to use. Available parsers: commonjs, requirejs [default: "commonjs"] --renderer Renderer to use. Available renderers: html, gfm, json [default: "html"] --stdout Direct all output to stdout instead of files [boolean] --ignore, -i Files or directories to ignore --help, -h Show this help

If [targets] is a directory, IcedDoc will recursively document all .icedfiles found under that directory.

If you wish to document several modules, make sure you generate all the docs with a single command -- this ensures that they will all appear in theindex.html file.

#### Note on Markdown headers ####

Markdown uses # characters for headers, e.g.

# Header 1 ## Header 2 ### Header 3 #### Header 4 ##### Header 5 ###### Header 6

As using a sequence of 3 or more #characters within a CoffeeScript block comment would end the comment block, IcedDoc allows for the\#escape sequence in docstrings. So instead of### Header, use \#\#\# Headeror##\# Header`. Ugly, but it works.

$3

IcedDoc uses the CoffeeScript parser to generate a parse tree for the given
source files. It then extracts the relevant information from the parse tree:
class and function names, class member functions, function argument lists and
docstrings.

Docstrings are defined as the first herecomment block following the class or
function definition. Note that regular single line comments will be ignored.

The resulting documentation information is then passed to an [eco][] template
to generate the html output.

$3

- Doctests

$3

- [Docco][] for literate programming style docs.
- [Codo][] for something more ruby than python.

$3

[CoffeeScript]: http://jashkenas.github.com/coffee-script/
[Sphinx]: http://sphinx.pocoo.org/
[Docco]: http://jashkenas.github.com/docco/
[Node.js]: http://nodejs.org/
[eco]: http://github.com/sstephenson/eco
[optimist]: http://github.com/substack/node-optimist
[Markdown]: http://daringfireball.net/projects/markdown/
[Codo]: http://github.com/netzpirat/codo

IcedDoc
=========

An API documentation generator for CoffeeScript
-----------------------------------------------

Thanks to apgwoz, IcedDoc can also generate wiki
pages for Github!

IcedDoc can also return your documentation as JSON, so you can run it through
an external documentation system such as [Sphinx][].

IcedDoc is inspired by the excellent [Docco][], and is intended for projects
that require more structured API documentation.

The docstring convention IcedDoc uses is inspired by Python, and looks like
this:

``coffeescript ###

`IcedDoc example documentation #`

This is a module-level docstring, and will be displayed at the top of the module documentation. Documentation generated by IcedDoc ###

method: (args) -> ### This is a method of MyClass ###

myFunc = (arg1, arg2, args...) -> ### This function will be documented by IcedDoc ### doSomething()`

The documentation generated from the above script can be seen here. For a more interesting example, here is the result of running iceddoc againstsrc/iceddoc.coffee.

`$3`

IcedDoc requires [Node.js][], [IcedCoffeeScript][], [eco][], and [optimist][]. Install using npm with the following command:

sudo npm install -g iceddoc

The -g option installs IcedDoc globally, adding the iceddoc executable to your PATH. If you would rather install locally, omit the -g option.

You can also install from source using cake. From the source directory, run:

sudo cake install

`$3`

IcedDoc can be run from the command line:

Usage: iceddoc [options] [targets]

If [targets] is a directory, IcedDoc will recursively document all .icedfiles found under that directory.

If you wish to document several modules, make sure you generate all the docs with a single command -- this ensures that they will all appear in theindex.html file.

#### Note on Markdown headers ####

Markdown uses # characters for headers, e.g.

# Header 1 ## Header 2 ### Header 3 #### Header 4 ##### Header 5 ###### Header 6

$3

Docstrings are defined as the first herecomment block following the class or
function definition. Note that regular single line comments will be ignored.

The resulting documentation information is then passed to an [eco][] template
to generate the html output.

$3

- Doctests

$3

- [Docco][] for literate programming style docs.
- [Codo][] for something more ruby than python.