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

Plugins

Launch Targets

• toga-css
  • parser()
    • parses doc blocks for CSS, LESS, and SCSS and generates AST
• toga-front-matter
  • parser()
    • visits first Comment.description and parses yaml front-matter
    • adds frontMatter property to file
• toga-js
  • parser()
    • parses jsdoc blocks and generates AST
• toga-perl
  • parser()
    • parses pod blocks and generates AST
• toga-php
  • parser()
    • parses phpdoc blocks and generates AST
• toga-python
  • parser()
    • parses pydoc blocks and generates AST
• toga-markdown
  • parser()
    • generates AST containing a single Comment.description
  • formatter()
    • visits Comment.description and Comment.tags.description nodes and formats values
• toga-closure-types
  • formatter()
    • visits Comment.tags.type nodes and formats values as Google Closure type expressions.
• toga-pod
  • formatter()
    • visits Comment.description and Comment.tags.description nodes and formats values
• toga-sample
  • formatter()
    • visits Comment.tags.sample nodes and generates a live demo in an iframe.
• toga-pulla
  • compiler()
    • A dark toga theme.
• toga-pura
  • compiler()
    • A light toga theme.

Optional base classes

• tunic
  • Base tag parser and AST generator
• trifle
  • Base tag formatter and AST tree walker
• trabea
  • Base compiler and indexer.

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