-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Shannon Moeller edited this page Jul 27, 2015
·
96 revisions
One tool and one destination for all project documentation including user guides, developer guides, styleguides, and api documentation for both front and back-end technologies.
Source code for an entire project will be streamed into documentation, via Transform Streams, a la gulp.
Usage: toga [options]
Options:
-h, --help output usage information
-c, --config <file> specify configuration file [togafile.js]
-d, --cwd <dir> specify working directory [.]
-v, --verbose log actions as they happen
-V, --version output the version number
var toga = require('toga'); // Loads toga.
toga.src(files); // Just `require('vinyl-fs').src`.
toga.dest(directory); // Just `require('vinyl-fs').dest`.
toga.add(...streams); // Turns streams into tributaries of another.
toga.map(callback); // Turns a map function into a transform stream.
toga.merge(...streams); // Turns multiple readable streams into one.var plugin = require('toga-plugin'); // Loads plugin.
plugin.parser(); // Returns transform stream which converts code file to ast.
plugin.formatter(); // Returns transform stream which modifies ast.
plugin.compiler(); // Returns transform stream which converts ast to documentation file.Any plugin may push static assets into the pipeline during the flush phase. Assets should be Vinyl files plus two properties:
-
isAsset{Boolean}Set totrue. -
fromPlugin{String}Name of the plugin from which the asset originated.
The assets should be static content that can be natively handled by a browser (html, css, js, image, video, etc). Each asset will be placed into a private directory specific to the plugin.
var toga = require('toga'),
css = require('toga-css'),
js = require('toga-js'),
md = require('toga-markdown'),
pura = require('toga-pura'),
config = {
src: [
'./src/docs/**/*.md',
'./src/assets/**/*.css',
'./src/assets/**/*.js'
],
dest: './web/docs'
};
toga
.src(config.src)
.pipe(css.parser())
.pipe(js.parser())
.pipe(md.formatter())
.pipe(pura.compiler())
.pipe(toga.dest(config.dest));var toga = require('toga'),
css = require('toga-css'),
js = require('toga-js'),
perl = require('toga-perl'),
md = require('toga-markdown'),
sample = require('toga-sample'),
pod = require('toga-pod'),
pura = require('toga-pura'),
config = {
manual: './src/assets/**/*.md',
css: './src/assets/**/*.css',
js: './src/assets/**/*.js',
perl: './lib/**/*.{pl,pm}',
dest: './web/docs'
},
manual = toga
.src(config.manual)
.pipe(md.parser())
.pipe(md.formatter()),
client = toga
.src(config.css)
.pipe(css.parser())
.pipe(js.parser())
.pipe(sample.formatter())
.pipe(md.formatter()),
server = toga
.src(config.perl)
.pipe(perl.parser())
.pipe(pod.formatter());
toga
.join(manual, client, server)
.pipe(pura.compiler())
.pipe(toga.dest(config.dest));- File -> Parser -> AST
- Parses source files and generates file-specific ASTs
- AST -> Formatter -> AST
- Visits AST nodes and compiles certain values to new values
- AST -> Compiler -> File
- Consumes file-specific ASTs and generates themed documentation files.
- Consumes parser-specific data and provides to theme as JSON