Generate Markdown from jsdoc style code comments.
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.
npm install docit
By default docit installs globally.
Probably easiest to provide a few examples:
-
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
-
Same as example 1. but only include files ending in .js:
docit --dir=lib --includeFiles=.js$
-
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
-
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
-
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:
Usage: docit [--config=] [--dir=
| ] [--out=
] [configOption] Options: --apiLabel The label to associate with an api tag comment. [default: "API:"] --apiLabelMarkdown The emphasis markdown for the api label. [default: "*"] --authorLabel The label to associate with an author tag comment. [default: "Author:"] --authorLabelMarkdown The emphasis markdown for the author label. [default: "*"] --codeHandler An optional code handler to handle code specific aspects of the output markdown. For example method signature and deriving method name from signature when not specified within the method comment. If specified codeHandler will override codeHandlers. [default: null] --codeHandlers Mappings of code handlers to expressions. Used to associated code handlers with corresponding files e.g. javascript files with .js files. [default: [{"\\.js":"./codehandlers/jsCodeHandler"}]] --config Path to a json configuration file defining custom options. All command line options - except this one and --help - will be used if present. Options specified directly on the command line override file loaded options. --constructorLabel The label to associate with a constructor tag comment. [default: "Constructor:"] --constructorLabelMarkdown The emphasis markdown for the constructor label. [default: "*"] --defaultModuleHeading The default heading for a any module that does not include one. This is only used when docit takes its input from stdio. Otherwise the input filename becomes the default module name. [default: "Module"] --deprecatedLabel The label to associate with an deprecated tag comment. [default: "Deprecated:"] --deprecatedLabelMarkdown The emphasis markdown for the deprecated label. [default: "*"] --dir Path to folder containing commented code to be processed by docit. Docit will recurse down any subfolders within this directory path. --includeFiles Comma separated list of file names or expressions used to determine the files to process when --dir option is employed. [default: null] --includeHRAfterMethod Include a horizontal rule after a method comment. [default: "true"] --includeHRBeforeMethod Include a horizontal rule before a method comment. [default: "false"] --includePrivate Include comments that are labelled as @private or @api private in the resulting md. [default: "false"] --help, -h This message. --horizontalRuleMarkdown Horizontal rule markdown string. [default: "* * *\n\n"] --methodHeadingMarkdown Method heading markdown. Single - and = characters are interpreted as underlines spanning the length of the method name. [default: "-"] --methodSignatureMarkdown Markdown to be applied to method signatures. [default: "###"] --moduleHeadingMarkdown Module heading markdown. Single - and = characters are interpreted as underlines spanning the length of the module name. [default: "="] --out Path of directory into which to write generated markdown files. This option is only valid when the --dir option is also specified. Each input file will result in a .md equivalent within the named directory. This directory and sub-directories where required will be created if they do not exist [default: "md"] --paramsHeading By default the list of method parameters is given a heading. This is that heading. [default: "Parameters"] --paramsHeadingMarkdown The markdown to be applied to the parameters list heading. [default: "####"] --paramsListMarkdown This markdown for the list style of method parameter comments. [default: "*"] --paramTypeMarkdown The emphasis markdown surrounding the type of a parameter. [default: "*"] --privateTypeLabel Label displayed adjacent to the type name when the type is private. [default: " (private)"] --privateVariableLabel Label displayed adjacent to the variable name when the variable is private. [default: " (private)"] --requiresLabel The label used to tag the line of modules upon which the current module depends. [default: "Requires:"] --requiresLabelMarkdown The emphasis markdown surrounding the requires label. [default: "*"] --returnHeading By default the description of the return value from a method is given a heading. This is that heading. [default: "Returns"] --returnHeadingMarkdown The markdown to be applied to the return heading. [default: "####"] --returnTypeMarkdown The emphasis markdown surrounding the type of the thing returned from a method. [default: "*"] --seeLabel The label to associate with a see tag comment. [default: "See:"] --seeLabelMarkdown The emphasis markdown for the see label. [default: "*"] --throwsHeading By default the description of any throws value from a method is given a heading. This is that heading. [default: "Throws"] --throwsHeadingMarkdown The markdown to be applied to the throws heading. [default: "####"] --throwsTypeMarkdown The emphasis markdown surrounding the type of an exception thrown by a method. [default: "*"] --typeNameMarkdown The markdown to be applied to type names. [default: "###"] --typesHeading Heading for types section in the generated markdown. [default: "Types"] --typesHeadingMarkdown Type heading markdown. Single - and = characters are interpreted as underlines spanning the length of the method name. [default: "-"] --variableNameMarkdown The markdown to be applied to variable names. [default: "###"] --variablesHeading Heading for variables section in the generated markdown. [default: "Variables"] --variablesHeadingMarkdown Varibales heading markdown. Single - and = characters are interpreted as underlines spanning the length of the method name. [default: "-"] --versionLabel The label to associate with a version tag comment. [default: "Version:"] --versionLabelMarkdown The emphasis markdown for the version label. [default: "*"]
First download. Then install dependencies with:
npm link
After that to run the tests:
npm test
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.