Aloha Editor

These guides help you to make your content editable and to develop Aloha Editor.

Guides Index ▸

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.

1 Write and modify guides

Guides are written using a ruby gem called guides. Setup guides

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:


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

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.

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

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

We are waiting for JSDoc 3 that will offer support for RequireJS modules, for now we use the SproutCore Documentation Generator that understands most of our annotations.

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

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

3.1 Installation of sc-docs

Requirements:

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

gem install sc-docs

3.2 Generating the documentation

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


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

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:


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

4 Changelog