Package Exports

docma

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (docma) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Docma

A powerful API documentation generator with a cool template engine.

Docma is a dev-tool written in Node.js to easily generate beautiful HTML documentation from your JS source files. It parses JSDoc comments into a Javascript object and builds a web app from the given template. The documentation data is then passed to the styled template within the global docma object.

Installation
Building Documentation
- Build Configuration
Docma Templates
Parsed Documentation
Change-Log
License

Installation

npm i docma --save-dev

Building Documentation

var Docma = require('docma');

Either by passing a configuration object.

// Docma.create(config) >> equivalent to >> new Docma(config)
Docma.create(config)
    .build()
    .catch(function (error) {
        console.log(error);
    });

Or by reading configuration from a JSON file.

Docma.fromFile(configFile)
    .then(function (docma) {
        return docma.build();
    })
    .catch(function (error) {
        console.log(error);
    });

Build Configuration

Option	Type	Default	Description
`src`	`String\|Array`		Required. One or more file/directory paths to be processed. This also accepts a Glob string or array of globs. e.g. `./src/*/.js` will produce an array of all .js files under `./src` directory and sub-directories.
`dest`	`String`		Required. Destination output directory path.
`template`	`Object`	`undefined`	Template specific configuration.
↳`template.path`	`String`	`"default"`	Either the path of a custom Docma template or the name of a built-in template. Omit to use the default built-in template.
↳`template.document`	`Object`	`undefined`	Configuration to be applied to the main HTML document of the output.
↳`template.document.title`	`String`	`""`	Title of the HTML document. (Sets the value of the `<title>` element.)
↳`template.document.meta`	`Array\|Object`	`undefined`	One or more meta elements to be set for the main HTML document. Set arbitrary object(s) for each meta element to be added. e.g. `[{ charset: "utf-8"}, { name: "robots", "content": "index, follow" }]`
↳`template.options`	`Object`	`undefined`	Options to be passed to the template. If any option is omitted in the build, default values within the `docma.template.json` configuration file of the template are used.
`dump`	`Boolean`	`false`	Set to `true` to output a JSON file from the documentation data. This will create a `documentation.json` file within the root of the output directory.
`jsdoc`	`Object`	`undefined`	JSDoc parse options.
↳`jsdoc.encoding`	`String`	`"utf8"`	Encoding to be used when reading source files.
↳`jsdoc.recurse`	`Boolean`	`false`	Specifies whether to recurse into subdirectories when scanning for source files.
↳`jsdoc.pedantic`	`Boolean`	`false`	Specifies whether to treat errors as fatal errors, and treat warnings as errors.
↳`jsdoc.access`	`String\|Array`	`undefined`	Specifies which symbols to be processed with the given access property. Possible values: `"private"`, `"protected"`, `"public"` or `"all"` (for all access levels). By default, all except private symbols are processed. Note that, if access is not set for a documented symbol, it will still be included, regardless of this option.
↳`jsdoc.private`	`Boolean`	`false`
↳`jsdoc.package`	`String`	`undefined`	The path to the `package.json` file that contains the project name, version, and other details. If set to `true` instead of a path string, the first `package.json` file found in the source paths.
↳`jsdoc.module`	`Boolean`	`true`	Specifies whether to include `module.exports` symbols.
↳`jsdoc.undocumented`	`Boolean`	`true`	Specifies whether to include undocumented symbols.
↳`jsdoc.undescribed`	`Boolean`	`true`	Specifies whether to include symbols without a description.
↳`jsdoc.relativePath`	`String`	`undefined`	When set, all `symbol.meta.path` values will be relative to this path.
↳`jsdoc.predicate`	`Function`	`undefined`	Alias: `filter`. This is used to filter the parsed documentation output array. If a `Function` is passed; it's invoked for each included `symbol`. e.g. `function (symbol) { return symbol; }` Returning a falsy value will remove the symbol from the output. Returning `true` will keep the original symbol. To keep the symbol and alter its contents, simply return an altered symbol object.
↳`jsdoc.hierarchy`	`Boolean`	`false`	Specifies whether to arrange symbols by their hierarchy. This will find and move symbols that have a `memberof` property to a `$members` property of their corresponding owners. Also the constructor symbol will be moved to a `$constructor` property of the `ClassDeclaration` symbol; if any.
↳`jsdoc.sort`	`Boolean\|String`	`false`	Specifies whether to sort the documentation symbols. For alphabetic sort, set to `true` or `"alphabetic"`. To additionally group by scope (static/instance) set to `"grouped"`. Set to `false` to disable.

Docma Templates

Docma templates are essentially web files that mainly make use of Dust.js internally.

Template Structure

/template                      Required
    ├─ docma.template.json       ✔︎      Template configuration.
    ├─ index.html                ✔︎      Main entry point. (defined in docma.template.json)
    ├─ /partials                 ✔︎      Partials to be compiled.
    │      └─ docma-main.html    ✔︎      Main partial file.
    ├─ /js
    ├─ /css
    ├─ /less
    ├─ ...
    :

Template Configuration

Docma templates should have a docma.template.json in the root of the template. This file defines template specific settings such as name of the template, version, the main entry point, document settings, ignored files, etc... This object can be accessed via docma.template.options within the template.

Config	Type	Default	Description
`name`	`String`		Required. Name of the template.
`version`	`String`	`"1.0.0"`	Version of the template. (semver).
`author`	`String`		Required. Author information.
`license`	`String`		Required. Name of the license. e.g. `"MIT"`
`main`	`String`	`"index.html"`	Name of the main HTML file which is the entry point of the template.
`ignore`	`Array`	`undefined`	List of files or directories to be ignored. Globs allowed.
`compile`	`Object`	`undefined`	Hash-map for files to be compiled. Each key should be a relative path to template directory and each value should be a relative path to output directory (including the file name). Currently only Javascript and Less files are supported. e.g. `{ "js/main.js": "js/main.min.js", "less/app.less": "css/app.css" }`.
`options`	`Object`	`undefined`	Template default options. This object will be merged with the template options defined at build-time.

Note that docma.template.json does not include any build configuration. This only configures the template.

HTML

<template>/index.html is the default entry point (main file) of the generated documentation. It should not include any Dust templates, but can of course include other custom HTML.

It should also include a <div id="docma-main"></div> which all the Dust templates will be compiled into. If you don't define this element, it will be created and dynamically appended to the body of the document.

Note that index.html is the default name of the entry point. You can customize this (name) in docma.template.json.

Example main file (index.html):

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
</head>
<body>
    <div id="docma-main"></div>
    <div id="my-footer"></div>
</body>
</html>

An empty body would also be valid but we want the footer to come after docma-main element. So it's explicitly defined.

Also, note that title of the document is not set. Since this is a template, title will be defined at build time and <title> element will be automatically added to the output document. See Build Configuration.

Partials

Put all Dust.js partials in <template>/partials directory. You should name your main partial as docma-main.html which will be compiled into <div id="docma-main"></div> in your main HTML.

A simple example for docma-main.html partial:

{#documentation}
    <h4 id="{.|$id}">{longname}</h4>
    <p>{description}</p>
{/documentation}

You can have sub directories within <template>/partials but all HTML files in these directories will be treated as if they were at the same level (under <template>/partials directory). For example, if you have a template at <template>/partials/widgets/menu.html, you should still include it like this: {>"menu"/} not {>"widgets/menu"/} or {>"partials/widgets/menu"/}. That's why all partials should have unique names.

These HTML files under <template>/partials are pre-compiled into Javascript and will be included as Dust JS templates. (Note that this directory will not be copied over to output directory.)

Docma-Web Core

When you build the documentation with your template, a docma-web.js will be generated (and linked in your main HTML); which is the core engine for the documentation web app. This will include everything the app needs such as the documentation data, compiled partials, dustjs engine, etc... (Note that the size of this script depends especially on the generated documentation data.)

See Docma Web API.

Custom Scripts

You have full control over the main HTML file so you can include any Javascript files in it. Docma web core will always be prepended before your scripts; so that you can safely access the global docma object.

Initializing the Template (Web App)

In order to make sure you execute some script after Docma is ready (and compiled partials are rendered), use the .ready() method of the global docma object.

// run this in any js file in the browser
docma.ready(function (err) {
    if (err) {
        console.log(err);
        return;
    }
    // initialize the template here
})

CSS & Less

You can include any .css files, anywhere in your template. Since you have control over the main HTML file, you can link any stylesheet in it. As a convention, it's recommended that you place all .css files under <template>/css.

You can also include less files in your template. Main less file(s) to be compiled, should be defined in docma.template.json.

Other Files

You can include any custom files anywhere in your template. They will be copied over into the output directory. If you need to include a file in the template but don't want it to be in the generated output; define it in the docma.template.json file, within the ignore setting.

Parsed Documentation

To investigate the parsed JSDoc documentation, enable the dump option that will create a documentation.json file within the root of the output directory.

If you have a problem with the parsed documentation data, open an issue @ jsdoc-x. (I'm the author.)

Change-Log

See CHANGELOG.md.

License

MIT. You don't have to include any copyright notice in your templates but I'd appreciate if you let people know about this tool so we can read better documentations.

docma