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.

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".
  • index Object - Searchable index record for lunr.
  • nav Array.<Object> - Document breadcrumbs for navtree generation.
  • blocks Array.<Code|Comment>
• 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

Navtree

Based on the advanced example:

Home
|- Manual
|  |- Getting Started
|  `- Installation
|- Styleguide
|  |- Content
|  |- Layout
|  `- Modules
|- JavaScript API
|  |- Constants
|  |- Controllers
|  |- Models
|  `- Views
`- Perl API
   |- ...
   `- ...

Plugins

• 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-google-annotations
  • formatter()
    • visits Comment.tags.type nodes and formats values
• 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-pura
  • compiler()
    • consumes ASTs
    • generates documentation files for source files
    • generates navigation trees
    • generates searchable json indexes

Resources

Useful

• http://lunrjs.com/

Inspiration

• 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