DocIt

Generate Markdown from jsdoc style code comments.

Background

I like the way GitHub presents project README.md files. I also like to include API documentation within the project README.md (assuming the API is not particularly large). Being quite lazy I did not want to have to keep my README.md API docs in sync and up-to-date each time I made a change to the commented code docs.

I looked around for some tool that would generate Markdown from my jsdoc style comments. (Oh, and the other thing I wanted was to have Markdown not HTML for my comments - so that it played nicely with README and other md docs.) So, anyway I didn't find anything that met all my needs and so decided to make one myself. DocIt is the result.

Installation

npm install docit

By default docit installs globally.

Usage

Probably easiest to provide a few examples:

1. Iterate over all the files in a folder - and recursively through its sub-folders. Each file is examined for jsdoc style comments. For each processed file an equivalent .md file is produced within a folder in the current working directory (by default) called "md" (by default). For each encountered folder an equivalent is created under the output "md" folder hierarchy:

    docit --dir=lib

2. Same as example 1. but only include files ending in .js:

    docit --dir=lib --includeFiles=.js$

3. Generate md comments from stdio using a javascript code handler for help with method signature, variable names etc. This command writes to stdout.

    docit --codeHandler="./codehandlers/jsCodeHandler" < module.js

4. Almost all configuration can be specified with a configuration file - an example is in the examples folder. Config that is missing and not specified on the command line uses a default value. Command line specified arguments override any equivalent within a config file. To specify a config file:

    docit --config=examples/sample_config.json

5. There are quite a few options for changing labels and markdown associated with tags and labels. To get the full usage that is shown below:

    docit --help

...which gives:

Testing

First download. Then install dependencies with:

npm link

After that to run the tests:

npm test

Contributing

Contributions are welcome. Please create tests for any updates and ensure jshint is run on any new files. Currently npm test will run jshint on all lib and test javascript as well as running all the tests.

Bugs & Feature Suggestions

https://github.com/allanmboyd/docit/issues