#Enyo.js API Reference Generator
The purpose of this project is to coordinate the accumulation and generation of the API documentation reference for enyo and its public libraries. It accomplishes this by leveraging available technologies, including itself, according to the limitations of its requirements at the time it was originally authored.
In the future, my hope is that the project will be able to better fulfill its ultimate purpose by coordinating all documentation and developer guidance into a single, normalized and cohesive source that is performant, extensible and comprehensive. For now, that is not possible.
The developer guide requires a unix-y shell. If you wish to build the full docs you will need Linux or Mac OS X. If you're feeling adventurous, you can convert the shell task into a grunt task (possibly with grunt-pandoc or one of the pandoc node modules.
Required Core Technologies
- Node.js - Everything relies on
- npm - Package manager for Node.js (installed with node)
- pandoc - A universal document converter, used to convert markdown to HTML. Be sure to make available on your path if it is not. (tip: 'brew install pandoc' on Mac)
Global npm Requirements
- Grunt.js - Command line client:
npm install -g grunt-cli
- Bower - Dependency management tool:
npm install -g bower
npm install and then
bower install in the enyo-docs directory to install these additional requirements:
- JSdoc3 - The backbone of our documentation syntax and parser/generator
- Nunjucks - The templating engine used to generate static HTML content
- Grunt.js - Task runner to help automate certain portions of generating and building the site
- Prism.js - The code/syntax highlighter in the output
File System Setup
The enyo-docs scripts assume that enyo and its libraries will be siblings and the libraries will be in the lib directory in the standard Bootplate way. In other words:
Parent +- enyo-docs +- enyo +- lib +- onyx +- layout +- moonstone +- canvas +- spotlight
Directories to be scanned (and other options for jsDoc) can be found in jsdoc-conf.json
Building The Docs
To build the docs, simply execute grunt in the enyo-docs directory:
Generated docs go into the output directory.
Two special 'macros' are used within the enyo docs source:
$api- Converted into the relative location of the root document directory. Used primarily in the developer-guide to locate api references.
$dev-guide- Converted into the relative location of the developer guide. Used primarily in the enyo source to point towards the developer guide articles.