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

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

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

AST

• Root
  • type String - Always "Documentation".
  • body Array.<CommentBlock>
• CommentBlock
  • type String - Always "CommentBlock".
  • description String
  • tags Array.<Tag>
  • trailingCode String
• CommentBlockTag
  • type String - Always "CommentBlockTag".
  • tag String
  • kind String
  • name String
  • description String

Example

/**
 * # Utilities
 *
 * A library of utility methods.
 *
 * @class Utilites
 * @static
 */
export default new class Utilities {
    /**
     * Escapes the given `html`.
     *
     * @method escape
     * @param {String} html String to escape. 
     * @return {String} Escaped html.
     */
    escape(html) {
        return String(html)
            .replace(...);
    }
}

{
    "type": "Documentation",
    "body": [
        {
            "type": "CommentBlock",
            "description": "# Utilities\n\nA library of utility methods.",
            "tags": [
                {
                    "type": "CommentBlockTag",
                    "tag": "class",
                    "name": "Utilities"
                },
                {
                    "type": "CommentBlockTag",
                    "tag": "static"
                }
            ],
            "trailingCode": "export default new class Utilities {"
        },
        {
            "type": "CommentBlock",
            "description": "Escapes the given `html`.",
            "tags": [
                {
                    "type": "CommentBlockTag",
                    "tag": "method",
                    "name": "escape"
                },
                {
                    "type": "CommentBlockTag",
                    "tag": "param",
                    "kind": "String",
                    "name": "html",
                    "description": "String to escape."
                },
                {
                    "type": "CommentBlockTag",
                    "tag": "return",
                    "kind": "String",
                    "description": "Escaped html."
                }
            ],
            "trailingCode": "    escape(html) {\n        return String(html)\n            .replace(...);\n    }\n}"
        }
    ]
}

Resources

Inspiration

AST

• https://github.com/jquery/esprima
• https://github.com/tj/dox

API

• http://jekyllrb.com
• http://metalsmith.io
• http://usejsdoc.org
• https://trulia.github.io/hologram/
• https://yui.github.io/yuidoc

UX

• https://www.gitbook.com/
• https://github.com/Polymer/docs
• http://perldoc.perl.org
• https://readthedocs.org
• http://styleguides.io
• https://tripit.github.io/slate