API documentation generator with a strict grammar and testing tools
Panino is an API documentation generation tool. It can read comments from your source files, or, parse Markdown files and generate the same documentation. Panino runs on Node.js, and uses Jade as its templating engine.
Panino parses your content following a strict, no-crap-allowed grammar that ensures correct and consistent documentation, because you've written it following a specific syntax. This means that there is a very specific set of rules and expectations as to how to write your documentation. These rules are not terribly hard or unweildly. Keeping documentation parsed through a grammar ensures thorough and consistent docs, no matter who it's written by. It can parse your source files in two ways:
For more help, including syntax and tag definitions, see the wiki.
[[ ]]"-notation linking (_e.g.
[[Class.foo]]renders to a link wrapped in a
Markdown is converted using namp.
npm installed. Then, you can can choose to install Panino globally:
npm install -g panino
I usually write a simple build script to do the work. Here's how that might look for a pdoc-like system:
var options =title : "Some test docs"output : './output'skin : "./skins/goose/templates/layout.jade"assets : "./skins/goose/assets"additionalObjs : "./additionalObjs.json"parseOptions : "./nodeParseOptions.json";var files = wrenchreaddirSyncRecursive"./nodejs_ref_guide"mapreturn pathjoin__dirname + "/nodejs_ref_guide/" + f;;paninoparsefiles optionsif errconsole.errorerr;processexit1;paninorender'html' ast optionsif errconsole.errorerr;processexit1;;;
Otherwise, you can try to call it from the CLI:
node panino [source_files_directory]
Panino has two processes: a parsing phase, and a rendering phase.
panino.parse() takes three arguments:
errand the parsed
panino.render takes four arguments:
c9acto provide a format compatible with Cloud9 IDE's auto completion tool. You can also create your own renderers.
Panino also supports reporting methods that are missing documentation. Currently, this is only supproted for
"jsd"-style parsing. There are two ways to report missing documentation:
report: true, Panino will print out a list of missing methods in a class, along with a percentage indicating the overall coverage.
reportOnly: true, Panino's
parse()will return a
reportObjectinstead of an
ast, as the second argument in the callback. You can then take this object and iterate over it any way you choose.
Regardless of whether or not you report them, missing methods are inserted into the final documentation.
This project is distributed under the MIT license.
Panino refers to a type of sandwich in Italy. Panini is its plural form, but is often mistakenly used as the singular. It seemed important to draw attention to the fact that what you're defining should represent what it actually is, in documentation and beyond.