h2. Documentation guidelines

After reading this guide, you will be able to:

* Write and modify guides
* Annote your code for the API documentation.
* Generate API documentation using jsdoc.

endprologue.

h3. Write and modify guides

Guides are written using a ruby gem called @guides@. "Setup guides":develop_aloha.html

The guides are stored in the directory @doc/guides@ in the Aloha Editor Distribution.

In order to preview the guides, you can use the just installed @guides@ command:

<shell>
cd doc/guides
guides preview
# now browse to http://localhost:9292
</shell>

The guides are stored in +source/*.textile+ files. They should be pretty self-explanatory, just open them
up and browse around. All changes you do to the guide source files can be previewed immediately using your
browser.

NOTE: If you create new files or change @guides.yml@, make sure to delete the +staging+ folder and restart
the guides server.

h3. Annotating code for API Documentation

We use JSDoc 2.4.0 for rendering JavaScript API Documentation. Please see @src/plugins/common/block/lib@ for
well-documented code.

NOTE: We are waiting for JSDoc 3 that will offer support for RequireJS modules, for now we use the
"SproutCore Documentation Generator":https://github.com/sproutcore/docs that understands most of our
annotations.

h3. Rendering API documentation

We use JSDoc syntax for the API documentation. This documentation is meant for programmers and implementors
as a reference of the code. General explanations and high-level overviews should go into the guides.

The actual documentation is rendered using the "SproutCore Documentation Generator", in short @sc-docs@.

NOTE: @SC-Docs@ is not as easy to set up as the @guides@ package. We will investigate how we can make
installation easier.

h4. Installation of sc-docs

Requirements:

* Ruby 1.9 and Rubygems
* node.js (for a special jsdoc-toolkit that is bundled with sc-docs)

<shell>
gem install sc-docs
</shell>

h4. Generating the documentation

A *preview* with an embedded server can be used to preview the API documentation. Run this in the Aloha
root directory:

<shell>
sc-docs preview src/plugins/common/block/lib -v -t docs.sproutcore.com
</shell>

This will render the API documentation of the block plugin (from +src/plugins/common/block/lib+).

When *generating* the documentation, an additional output directory +output_dir+ must be specified:

<shell>
sc-docs generate src/plugins/common/block/lib -v -t docs.sproutcore.com -o output_dir
</shell>


h3. Changelog

* July 6, 2011: Initial version by "Sebastian Kurfürst":credits.html#skurfuerst and "Christopher Hlubek":credits.html#hlubek