Inspired heavily by docco,
indoc is a quick-and-dirty documentation generator written in plain
JavaScript. It can be run either from the command line or included as
a node.js library.
Unlike docco, indoc has the concept of a project; instead of
having a hacky "Jump To" menu, indoc has an integrated file listing
on each generated page. (Check it out on the left.)
The recommended usage is to install indoc globally and use a local
project config file with the -c command line option.
$ ls
bin/ lib/ src/ README.md indoc.json
$ more indoc.json
{
"name": "Mousetrap Simulation Library"
"owners": "Tom",
"output": "docs",
"readme": "README.md",
"version": "package.json",
"files": [
"src/**/*.js"
]
}
$ indoc -c indoc.json
info: Generated "README.md"
info: Generated "src/animal.js"
info: Generated "src/cat.js"
info: Generated "src/mouse.js"
info: Generated "src/trap.js"
info: Successfully generated 5 files
$ ls
bin/ docs/ lib/ src/ README.md indoc.json
$ ls docs/
index.html README.md/ animal.js/ cat.js/ mouse.js/ trap.js/
$ npm install -g indoc
The command indoc should now be available.
Alternatively, use
npm install indoc
to use the library as a node.js module.
$ indoc [options] files...
Sets a config file to read configuration options from. If used, the rest of the arguments are ignored.
Example config file:
{
"name": "Mousetrap Simulation Library"
"owners": "Tom",
"output": "docs",
"readme": "README.md",
"version": "package.json",
"files": [
"src/animal.js",
"src/cat.js",
"src/mouse.js",
"src/trap.js"
]
}Displays help. If you need to consult the README to find this
argument, you shouldn't be using indoc in the first place.
Displays the program's semver; for example, 0.1.0, then exits.
$ indoc --version
0.3.2
$
Provide a README file, to be used on the project's overview page. This file will be parsed as Markdown.
Set the user-facing name of the project.
Set the output directory (the default is docs).
Sets a string. By default, it's contributors. This string is at the
footer of every generated page.
Sets the project version. This is displayed on every page. The special
string package.json will attempt to read the package.json file and
find the version there.
var indoc = require('indoc');
var project = new indoc.Project({
name: 'Mousetrap Simulation Library',
owners: 'Tom', // "Copyright 2016 Tom"
output: 'docs',
readme: 'README.md',
version: 'package.json', // the special string "package.json" will open the file "package.json" and read the version string there
links: {
github: "https://github.com/tom/mousetrap-sim",
twitter: "https://twitter.com/mousetrapsim"
},
files: [
'src/animal.js',
'src/cat.js',
'src/mouse.js',
'src/trap.js'
]
});
project.run(function(err, data) {
console.log('Generated ' + data.total + ' files!');
});You can reference external links with the links key in
options. Currently supported link types are:
githubtwitterhome
The languages supported by indoc are stored in lib/languages.json in the following format:
"JSFOO": {
"extensions": [
"js", "json"
],
"name": {
"hljs": "JavaScript", // the language type for Highlight.js, 'auto' to autodetect, or `null` for Markdown
"human": "JavaScript", // the human-readable language name. If not present, the name of the language
// (JSFOO, above) is used instead.
"abbr": "JS" // The short abbreviation of the language. If not present, the first item in
// "extensions", above, is used.
},
"single": [ "//", ";;" ],
"multi": [
["/*", "*", "*/"]
],
"ignore": [
"eslint-disable"
]
}Right now, if there's a language that's not included or not set up to
your liking, you can use the languages field of the options
argument of the indoc.project to add new languages or modify
existing ones:
var project = new indoc.Project({
name: 'Mousetrap Simulation Library',
...
files: [ ... ],
languages: {
'SubScript': {
extensions: [
'sub', 'sbs'
],
name: {
hljs: 'JavaScript', // the language type for Highlight.js, or null
human: 'JavaScript',
abbr: 'JS'
},
single: [ '//', ';;' ], // a single-line comment starts with '//' or ';;'
multi: [
['/*', '*', '*/'] /* See below for an explanation of how multiline comments work. */
],
ignore: [
'hideme!' // hideme! (this comment will be ignored)
]
}
}
});
/* a multi-line comment starts with '/*' and ends with '*/'.
* Optionally, if a line starts with '*', it will be removed
* to allow for indented multi-line comments, like this one.
* Both `single` and `multi` allow for multiple comment formats.
* */At the moment, indoc is very, very new. It would probably be better
if, instead of contributing code, you
open new issues. I'd like to
see indoc stabilize more before changing major areas of its
functionality.
Just edit lib/languages.json and open a PR with the languages you've
included. Make sure that the JSON still validates and that indoc
runs without any problems. Thanks!
Copyright (c) 2016 ZLSA Design.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.