— But wait! We have jsDoc, docco, documentation and umpteen other doc generators. Do we really need another one?

— We’ve looked through all umpteen of them. We even heavily used one or the other. But what we’re after is flexibility. If you’re a perfectionist, construct your docs from the ground up, and polish them down to the very last detail to suit them to your liking. If you want decent results quickly, choose a ready-made theme. Probably you’re somewhere in between – so take a preset and tweak it a bit. We’re talking about total flexibility. This wasn’t possible before.

— OK, I get it now. But if you want generic stuff, there’s gulp, and there was grunt. Aren’t they de-facto tools for such things?

— Gulp is very flexible. But it’s designed to process individual files. Just like metalsmith is designed to process whole directories. We need another abstraction. We have functions, objects, or CSS classes to document – and often we don’t even care what file they’re in. We call these things docs. Gulp works with files, and doxie works with docs.

— Well, now it becomes clear. Thanks for the interview.

— You’re very welcome.

Made with doxie

These readmes have been rendered with doxie:

• git-tips/tips
• studio-b12/tape-css
• npm-scripts/scripts
• studio-b12/bare-select
• parametric-svg/patch
• studio-b12/mve
• studio-b12/polydox

Installation

doxie is a command-line tool.

$ npm install --global doxie

doxie itself is just a slim core. Every feature is a plugin. So if you want to run doxie --filter --output, make sure you install doxie.filter and doxie.output first:

$ npm install --global doxie.filter doxie.output

Speaking of plugins, most of them are compatible with dox

$ npm install --global dox

Usage

SYNOPSIS

Usage: doxie [--help|-h]
   or: doxie (--<plugin> [<plugin options>])+

DESCRIPTION

http://npm.im/doxie The simplest docs generator you’ve seen

All it does is take an array of data and pipe it through a bunch of plugins (functions). Just keep in mind that many plugins will expect data compatible with http://npm.im/dox. That’s it.

doxie operates over stdio.

EXAMPLES

High level:

$ dox < myLibrary.js | doxie  \
$   --drop @private           \
$   --drop @protected         \
$   --sort by @module         \
$   --preset 1-liners         \
$   --inject into Readme.md

Low level:

$ doxie                                                      \
$   --filter build/filter.js                                 \
$   --render build/template.js                               \
$   --output                                                 \
$   < data.json                                              \
$   | cat build/Readme.overview.md - build/Readme.footer.md  \
$   > Readme.md

Note that not all of the above plugins are available at the time of writing.

POPULAR PLUGINS

--filter [<filter function (default: .doxie.filter.js)>]
    Filter comments through a custom function.
    <http://npm.im/doxie.filter>

--render [<template function (default: .doxie.render.js)>]
    Render comments with a simple, flexible function.
    <http://npm.im/doxie.render>

--output
    Output rendered comments.
    <http://npm.im/doxie.output>

For an up-to-date list of available plugins visit https://www.npmjs.com/browse/keyword/doxie-plugin.

License

MIT © Studio B12 GmbH