— 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.
— 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.
These readmes have been rendered with doxie:
doxie is a command-line tool.
$ npm install --global doxie
$ npm install --global doxie.filter doxie.output
Speaking of plugins, most of them are compatible with dox
$ npm install --global dox
Usage: doxie [--help|-h] or: doxie (--<plugin> [<plugin options>])+
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.
dox < myLibrary.js | doxie \ --drop @private \ --drop @protected \ --sort by @module \ --preset 1-liners \ --inject into Readme.md
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.
--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.