Home

Toga

Goal

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.

Process

Source code for an entire project will be streamed into documentation, via Transform Streams, a la gulp.

Interfaces

CLI

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

API

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.

Plugin API Convention

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.

Static Assets

Any plugin may push static assets into the pipeline during the flush phase. Assets should be Vinyl files plus two properties:

isAsset {Boolean} Set to true.
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.

Example

Basic

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));

Advanced

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');

Specs

Flow

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly