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
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 folder and restart the guides server.
2 Annotating code for API Documentation
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 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
- 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