Docma CLI

Instead of programmatically executing the Docma builder, you can directly use the CLI from your console.

Although the CLI does not provide each build configuration as a command-line option; it still supports all of them via the -c option which you can set the configuration file's path to. (i.e. path/to/docma.json)

docma [options]

Option / Alias                     Parameter Description
-h --help Output CLI usage information.
-v --version Output the Docma version number.
-c --config <path> Docma JSON configuration file path. You can define all build options within this file. Any option (below) set via CLI will override the value defined in this file.
-s --src <[name:]path> Source file path. To define multiple source files, this option can be used more than once. To group/name source files, prefix each source path with name:. e.g. -s a.js -s mylib:b.js -s mylib:c.js -s other:d.js
-d --dest <path> Output destination directory path.
--clean Empty destination directory before building docs. Use with caution!
--web-logs (Debug) Enable logs in the browser console, for the generated SPA.
-V --verbose (Debug) Output verbose logs to consoles.
--nomin (Debug) Disable minification for the generated SPA assets. (e.g. js, css files)
--jd-out (Debug) Output one or more [name.]jsdoc.json files that include documentation data for each (grouped) javascript source. name is the group name you give when you define the source files. This is useful for investigating the raw JSDoc output.
--debug Enable all debugging options.
Equivalent to: --web-logs -v --nomin --jd-out
-q --quiet (Debug) Disable build logs for the Node console.

Note: If no debug options are set in the CLI arguments (such as --debug, -q, --nomin, --jd-out, -v, --web-logs); the bitwise debug value from the config file is used, if set.

Examples

# Build documentation with a Docma configuration (JSON) file:  
docma -c path/to/docma.json

# If a `docma.json` already exists in the current directory, simply:  
docma

# Output to a directory, other than the one defined in the config file:  
docma -c path/to/docma.json -d path/to/docs

# Re-define source files (ignore the ones defined in the config file):  
docma -c path/to/docma.json -s path/to/lib-1.js -s path/to/lib-2.js

# Define name-grouped source files:  
docma -c path/to/docma.json -s mylib:path/to/lib-1.js -s mylib:path/to/lib-2.js

Commands

docma serve [path] [options]

You can run a mock server for testing the generated SPA with this command. This will boot up a simple static-files server. If path is omitted, it will look for a docma.json or .docma.json in the current working directory. If found, the configured destination will be served. If no Docma configuration file is found, current working directory will be served.

Run docma serve from your project root, without any target path. It will auto-adjust to your docma.json configuration.

Additionally, you can use the following options:

Option / Alias                     Parameter Description
-h --help See help for serve command.
-p --port <number> Port number to bind the mock-server on. Default: 9000
-b --base <string> Base path for the SPA. Default: /
-q --quiet Disable request logs for the mock-server.

Examples

# Serve generated SPA at the default port (9000):  
docma serve  # omitting target path if current working dir has a docma.json

# Configure a custom port and serve:  
docma serve -p 8080

# Serve without request logs:  
docma serve -q

# Setting a target path to be served.  
docma serve path/to/dir

docma template init [path]

Initializes a new Docma template within the given root directory. This generates a skeleton for a template. You should go through the generated files and modify them as you see fit. Check out generated package.json for module configuration.

Once you complete your template, make sure you publish it to npm. Please test your template thoroughly before you publish.

docma template doctor [path] [options]

Useful for Docma template authors; diagnoses a given Docma template, looking for structural and configurational issues.

You can use the following options:

Option / Alias                     Parameter Description
-h --help See help for template doctor command.
--first Whether to stop on first fault when diagnosing the template.

Examples

# Initialize a new Docma template module:  
docma template init path/to/project

# Initialize a new Docma template module, in current working directory:  
cd path/to/project && docma template init

# Diagnose a Docma template module:  
docma template doctor path/to/project

# Diagnose a template in current working directory:  
cd path/to/project && docma template doctor

# Stop immediately at the first fault found:  
docma template doctor path/to/project --first