Home

Toga

http://togajs.com

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

Toga API

var toga = require('toga'); // Loads toga.

toga.src(files);      // Just `require('vinyl-fs').src`.
toga.dest(directory); // Just `require('vinyl-fs').dest`.
toga.join(stream...); // Just `require('multistream')`.

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 the asset is from.

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
    .join(manual, client, server)
    .pipe(pura.compiler())
    .pipe(toga.dest(config.dest));

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

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

Specs

AST

• Root
  • type String - Always "Document".
  • meta Metadata - Document metadata for navtree generation.
  • blocks Array.<Code|Comment>
• Metadata
  • type String - Always "Metadata".
  • title String
  • id String
  • parent String
• Code
  • type String - Always "Code".
  • body String
• Comment
  • type String - Always "Comment".
  • description String
  • tags Array.<Tag>
• Tag
  • tag String
  • type String
  • name String
  • description String

Resources

Inspiration

• http://tripit.github.io/slate
• http://usejsdoc.org
• http://yui.github.io/yuidoc
• https://github.com/tj/dox
• https://readthedocs.org
• http://perldoc.perl.org
• http://www.styleguides.io
• http://jekyllrb.com
• http://www.metalsmith.io
• https://github.com/Polymer/docs