vcl-doc-gen

VCL Documentation Generator

A documentation generator for the VCL based on a set of modules or an entry point package.json and its recursive dependencies. In most cases you want the doc-gen to use a single package.json listing all dependencies from your project. The output will look like the VCL's module browser.

You can also generate a JSON doc only, which includes all infos needed to display it in a browser for example. This is what the vcl-doc-client uses to render the documentation.

Under the Hood

The main purpose of this module is to generate a JSON data structure in which all documentation relevant information is collected. Modules considered need to have a vcl property in the package.json file according to the structure explained here.

Each module's documentation file (defaults to README.md) is picked and copied into the JSON structure as well as the meta data from package.json.

The browsable HTML output is generated by the vcl-doc-client module based on the input JSON data.

Usage

CLI

npm -g i vcl-doc-gen
cd someProject
vcl-doc-gen --entry ./package.json --output doc.html

Arguments

All arguments are optional.

Option	Default	Description
--name	VCL Documentation	Browser Title & Main heading
--output	vcl-documentation.html	Output HTML file
--entry	./package.json	Entry file.
--basePath	current working dir

See Options for a more detailed description.

Local CLI

npm install --save-dev vcl-doc-doc-gen
./node_modules/.bin/vcl-doc-gen

Generate HTML

var docGenerator = require('vcl-doc-gen');

docGenerator.generateHtml({
  name: 'VCL Documentation',
  entryPackage: './package.json',
  output: './documentation.html'
});

Generate JSON

var docGenerator = require('vcl-doc-gen');

docGenerator.generate({
  name: 'VCL Documentation',
  entryPackage: './package.json',
  output: './doc.json'
});

Options

name

The name of the documentation. When using vcl-doc-client this will be displayed in the header and set as the page title.

Default: name: 'VCL Documentation'

entryPackage

The package that the doc-gen should parse to find all VCL dependencies and generate the documentation from.

Example: entryPackage: './package.json'

packages

You can put a list of paths to additional packages here or use this as an lternative to the entryPackage option and set your packages manually.

Example: packages: ['../vcl-test', './some/package']

output

The file to output the finished json doc.

Default: output: './doc.json'

removeTopHeading

With this option, all level 1 headings from the package readme files are removed. Defaults to true, because most packages have the package name as the first heading and the vcl-doc-client does already display the package name above the readme.

Default: removeTopHeading: true

basePath

The base path.

Example: basePath: './my-project'