Hikki
Hikki is Japanese for Scribe, or notes. This node module with take comments from your code and outputs them as markdown files in a different directory.
Why?
Generating documentation from code is great, you do not have to context switch between writing docs and writing code, it all lives in the same place. There are a bunch of tools that already do this, like docco and dox. Hikki takes a differnt approach to this in the fact that it want to output markdown files and put them in you repo or another directory that you specify. The reason for this is that sites like Github, Butbucket and Gitlabs are already in our workflow, so we leverage their capabilities and allow those sites to display our docs for us. This then removes the dependecy of running a server to display these docs.
Install
Currently this is not on npm, but if you clone down this repo then run.
npm link
That will symlink the bin to you npm install and you will have the hikki
command globally. Also you can add it to you package.json and then point towards this repo using this method.
Usage
hikki src/js/**/*.js
That is all that is required. You need to point it towards the files you want to create docs from ( it has glob support :) ). By default this will output Line Delimited Objects
but if you specify an output using.
hikki src/js/*.js -o docs
It will then output Markdown files into that directory.
Other options
flags | description |
---|---|
-o --output | directory relative to CWD to output markdown files |
-e --exclude | patterns to exclude from processing eg. vendor |
-v --verbose | will output to console when a markdown file is written |
-b --base | base of source, to exclude path when creating markdown files |
-f --files | a string or array of files to pull data from, glob support |
-p --prefix | a string to prefix comment blocks to indicate its for docs |
when using globs your terminal will do this automatically and sometime the results are not expected eg.
**/*.js
will not get root level javascript files if you have this issue just add to a string eg."**/*.js"
and our glob library will catch the root level files.
JS api
Right now the is a JS api but it is not super intuitive. Eg.
var hikki = Writable = Writable ws = ; ws; ;
A better API should be made for advanced usage.