named after the documenter of the dock of some nameless bay somewhere.
real sick. check it:
requirearchitecture to store settings per-project for generating documentation. that way you can just type
otisin the project root -- nothing more. finally, you'll be able to get that frontal lobotomy without inconveniencing your coworkers -- you've earned it!
easy_install pygments for you, but if not, it's not very hard to get it up and running manually)
npm install -g otis
$ otis [use <config>] [options] [files to document]
use <config> is present, otis will attempt to load config files in the
... and will bail if neither of the latter two could be found, assuming you
have made a grave error of some kind. otis will not look for
./otis.config.js under these circumstances.
when there is no 'use ' argument specified, otis will use this order instead:
otis loads all of the config files it can find and merges them together, giving "override precedence" to the files listed closer to the bottom in the two lists above.
so for example, if you have a home directory otis.config.js and also a current directory otis.config.js, otis will load both, and will allow anything in the current directory config to override the home directory config.
they're just your typical input files. four little NBs, though:
inDirargument (if you give one).
-i, --inDir Input directory (defaults to current dir)-o, --outDir Output directory (defaults to ./doc)-t, --tplDir Directory containing dox.<ext>, code.<ext>, and tmpl.<ext>-e, --tplEngine Template parser (see github.com/visionmedia/consolidate.js)-n, --tplExtension Template file extension-m, --markdownEngine Only two choices, cowboy.-u, --onlyUpdated Only process files that have been changed-c, --colourScheme Color scheme to use (as in pygmentize -L styles)-y, --css CSS file to include after pygments CSS (you can specify this flag multiple times)-T, --tolerant Will parse comments without a leading ! (ex: "/**! ...")-w, --watch Watch on the input directory for file changes (experimental)-I, --ignoreHidden Ignore hidden files and directories (starting with . or _)-s, --sidebarState Whether the sidebar should be open or not by default-x, --exclude Paths to exclude-W, --writeConfig Write 'otis.config.js' in PWD using the options provided.-h, --help Show this help text.
you can have otis auto-generate a config file for you in the current
directory freezing whatever flags you pass to it into a reusable command.
if the current directory or
~/.otis contain an
otis.config.js file, all you
have to type to generate beautiful, easily-navigable documentation is
(mind the dot)
but, just for reference's sake, an
otis.config.js file will basically look
moduleexports =inDir: './'outDir: './doc'tplDir:tplEngine: 'jade'tplExtension: 'jade'markdownEngine: 'showdown'onlyUpdated: falsecolorScheme: 'friendly'tolerant: falseignoreHidden: truesidebarState: trueexclude: 'otis.config.js,*.md,doc,node_modules,bin';
yep, just a regular old node.js module.
note that the keys on this object correlate 1 to 1 with the available command-line options. that's the plan moving forward indefinitely.
there's currently only one file that otis is hard-coded to look for in
otis.config.<config>.js as the case
however, it's also a great place to store your custom templates, custom css files, etc. as well. only difference is that you have to tell otis (yes, in a config file) that he should look there for them.
don't waste your
~/.otis. put it to good use.
$ otis .
$ otis -i src -o documents
$ otis -o documents src
$ otis -o documents src/*
note that in the first example, the contents of
src will be mapped directly
documents whereas in the second and third examples, the files will be
i will bequeath to you the secret, ancient command i use to generate this project's documentation. it does all of the following:
gh-pagesbranch of this repo
README.mdfile, and a few other things
the command is:
$ otis .
hahaaaaa, gotcha! see? use otis.config.js files. they're great.
you may not want every single comment in your code to end up as a line in your
documentation. otis assumes that to be the case by default and will only
process a comment as documentation if the very first character after the
comment delimiter is
! (an exclamation point).
so, depending on the language, something like the following:
if you want to disable this behavior so that all comments become
documentation, just use the
-T flag on the command line, or
tolerant: true in your
these are exactly as in
pygmentize -L styles:
at the moment, only:
bryn austin bellomy < email@example.com >
otis owes unrepayable debts to:
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSEVersion 2, December 2004Copyright (C) 2004 Sam Hocevar <[firstname.lastname@example.org]()>Everyone is permitted to copy and distribute verbatim or modifiedcopies of this license document, and changing it is allowed as longas the name is changed.DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION0. You just DO WHAT THE FUCK YOU WANT TO.