Home
Shannon Moeller edited this page Jan 16, 2016
·
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.symlink(directory); // Just `require('vinyl-fs').symlink`.
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
.merge(manual, client, server)
.pipe(pura.compiler())
.pipe(toga.dest(config.dest));import toga from 'toga';
import css from 'toga-css';
import js from 'toga-js';
import perl from 'toga-perl';
import md from 'toga-markdown';
import sample from 'toga-sample';
import pod from 'toga-pod';
import pura from 'toga-pura';
const manual = toga
.src('./src/assets/**/*.md')
.pipe(md.parser())
.pipe(md.formatter());
const client = toga
.src('./src/assets/**/*.{css,js}')
.pipe(css.parser())
.pipe(js.parser())
.pipe(sample.formatter())
.pipe(md.formatter());
const server = toga
.src('./lib/**/*.{pl,pm}')
.pipe(perl.parser())
.pipe(pod.formatter());
toga
.merge(manual, client, server)
.pipe(pura.compiler())
.pipe(toga.dest('./web/docs'));import toga from 'toga';
const manual = toga
.src('./src/assets/**/*.md')
.parse('markdown')
.format('markdown');
const client = toga
.src('./src/assets/**/*.{css,js}')
.parse('css')
.parse('js')
.format('sample')
.format('markdown');
const server = toga
.src('./lib/**/*.{pl,pm}')
.parse('perl')
.format('pod');
toga
.merge(manual, client, server)
.compile('pura')
.dest('./web/docs');- 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