Fork me on GitHub

NDoc - JavaScript documentation generator

Build Status

NDoc is an inline comment parser and JavaScript documentation generator written in Node.JS. This project was inspired by PDoc. It tries to keep compatibility, but has some differences:

  • NDoc is primarily a CLI tool, so you don't need to code your documentor, although it can be easily used as library.
  • Clarified EBNF syntax. Definitions now MUST be separated with an empty line from the following comments.
  • Added options for deprecated tag: you can set versions, when tag was deprecated and when method/property will be removed.
  • Added new tags: read-only, internal, chainable
  • Events support.

How to Install

We suppose that you already have Node and npm installed. If not - try nvm.

npm install -g ndoc

Usage

usage: ndoc [-h] [-v] [--exclude PATTERN] [-o PATH] [--use PLUGIN]
            [--alias MAPPING] [-r RENDERER] [--link-format FORMAT]
            [-t TEMPLATE] [--show-all] [--package PACKAGE] [--index FILE]
            [--gh-ribbon URL] [--broken-links ACTION] [--noenv]
            PATH[PATH ...]

Positional arguments:
  PATH                            Source files location

Optional arguments:
  -h, --help                      Show this help message and exit.
  -v, --version                   Show program's version number and exit.
  --exclude PATTERN               Glob patterns of filenames to exclude (you 
                                  can use wildcards: ?, *, **).
  -o PATH, --output PATH          Resulting file(s) location.
  --use PLUGIN                    Load custom plugin.
  --alias MAPPING                 Registers extensions alias. For example 
                                  `cc:js` will register `cc` extension as an 
                                  alias of `js`
  -r RENDERER, --render RENDERER  Documentation renderer (html, json). More 
                                  can be added by custom plugins.
  --link-format FORMAT            View sources link (no links by default) 
                                  format. You can use `{file}` and `{line}` 
                                  and any of `{package.*}` variables for 
                                  interpolation.
  -t TEMPLATE, --title TEMPLATE   Documentation title template. You can use 
                                  any of `{package.*}` variables for 
                                  interpolation. DEFAULT: `{package.name} 
                                  {package.version} API documentation`
  --show-all                      By default `internal` methods/properties 
                                  are not shown. This trigger makes ndoc show 
                                  all methods/properties
  --package PACKAGE               Read specified package.json FILE. When not 
                                  specified, read ./package.json if such file 
                                  exists.
  --index FILE                    Index file (with introduction text), e.g. 
                                  README.md file.
  --gh-ribbon URL                 Add "Fork me on GitHub" ribbon with given 
                                  URL. You can use any of `{package.*}` 
                                  variables for interpolation.
  --broken-links ACTION           What to do if broken link occurred (show, 
                                  hide, throw). DEFAULT: `show`.
  --noenv                         Ignore .ndocrc

Syntax

NDoc Syntax. It is similar to PDoc one, with some extentions (see start of this doc for details).

For developers

You can generate prototype documentation for test:

make test

Then open ./tests/prototype-doc/index.html. Here is hosted example.

Custom parsers and renderers

You can create and use your own parser/renderer via --use option. Get one of the parsers or renderers as a base template, copy it into separate folder. Create package.json and modify it to fit your needs. Then attach it with --use my-module argument.

Using NDoc as module

You can use NDoc as module, for example, to override default options processing.

var NDoc = require('ndoc');


var options = {
  linkFormat  : 'http://example.com/{file}#{line}',
  output:     : 'doc'
};


NDoc.parse(['lib/my-module.js'], options, function (err, ast) {
  if (err) {
    console.error(err);
    process.exit(1);
  }

  NDoc.render('html', ast, options, function (err) {
    if (err) {
      console.error(err);
      process.exit(1);
    }
  });
});

License

This project is distributed under MIT license.

Sections

  • plugins

    Built-in plugins. These plugins are automatically registered.

namespace

cli

Description

Instance of ArgumentParser with some small improvements and additional methods.

Extra Actions

We provide some extra-actions for our instance of ArgumentParser.

store+lazyChoices

Allows you define actions with lambda-like choices

cli.addArgument(['--foobar', {
  // ...
  choices: function () { return ['a', 'b', 'c']; }
});
store+readJSON

Allows specify an action that set value as an object from the file specified in the argument.

store+readFile

Allows specify an action that will set value as a string read from the file specified in the argument.

See Also

class method

cli.findFiles

    • cli.findFiles(paths[, excludes], callback(err, files))
      • Void
    • paths
      • Array
    • List of directories/files

    • excludes
      • Array
    • List of glob patterns.

    • callback
      • Function

Finds all files within given paths excluding patterns provided as excludes.

Excluding paths

Each element of excludes list might be either a String pattern with wildcards (*, **, ?, etc., see minimatch module for pattern syntax) or a Function that returns boolean (whenever excude or not) and executed with (filename, lstats).

var excludes = [
  'lib/parser-*.js',
  function (filename, lstats) {
    // skip any symlink
    return lstats.isSymbolicLink());
  }
];
See Also
class method

cli.readEnvFile

    • cli.readEnvFile(file)
      • Void
    • file
      • String
    • File with CLI arguments

Inject CLI arguments from given file into aprocess.argv. Arguments can be listed on multi-lines. All lines starting with # will be treaten as comments.

Example
# file: .ndocrc
--title "Foobar #123"

# We can have empty line, and comments
# as much as we need.

lib

Above, equals to:

--title "Foobar #123" lib
class

NDoc

Description

Handles documentation tree.

Class properties

class method

NDoc.extensionAlias

    • NDoc.extensionAlias(alias, extension)
      • Void
    • alias
      • String
    • Extension as for the parser, e.g. 'cc'

    • extension
      • String
    • Extension as for the parser, e.g. 'js'

Registers alias of the extension parser.

Example

Parse all *.cc files with parser registered for *.js

ndoc.extensionAlias('cc', 'js');
See Also
class method

NDoc.parse

    • NDoc.parse(files, options, callback)
      • Void
    • files
      • Array
    • Files to be parsed

    • options
      • Object
    • Parser options

    • callback
      • Function
    • Notifies parsing is finished with callback(err, ast)

Execute name parser against files with given options.

Options
  • linkFormat: Format for link to source file. This can have variables:
    • {file}: Current file
    • {line}: Current line
    • {package.*}: Any package.json variable
class method

NDoc.registerParser

    • NDoc.registerParser(extension, func)
      • Void
    • extension
      • String
    • Extension suitable for the parser, e.g. 'js'

    • func
      • Function
    • Parser function func(source, options, callback)

Registers given function as name renderer.

class method

NDoc.registerRenderer

    • NDoc.registerRenderer(name, func)
      • Void
    • name
      • String
    • Name of the renderer, e.g. 'html'

    • func
      • Function
    • Renderer function func(ast, options, callback)

Registers given function as name renderer.

class method

NDoc.render

    • NDoc.render(name, ast, options, callback)
      • Void
    • name
      • String
    • Renderer name

    • ast
      • Object
    • Parsed AST (should consist of list and tree)

    • options
      • Object
    • Renderer options

    • callback
      • Function
    • Notifies rendering is finished with callback(err)

Execute name renderer for ast with given options.

class method

NDoc.use

    • NDoc.use(plugin)
      • Void
    • plugin
      • Function
    • Infection plugin(NDocClass)

Runs given plugin against NDoc base class.

Examples
NDoc.use(require('my-renderer'));
class property

NDoc.cli

class property

NDoc.VERSION

    • NDoc.VERSION
      • String

NDoc version.

section

Plugins section

internal

Description

Built-in plugins. These plugins are automatically registered.

Namespaces

namespace

Parsers

Description

Built-in parser plugins.

Class methods

class method

Parsers.ndoc

internal
    • Parsers.ndoc(NDoc)
      • Void

Registers NDoc parser as ndoc.

Example
NDoc.parse(files, options, function (err, ast) {
  // ...
});
namespace

Renderers

Description

Built-in renderer plugins.

Class methods

class method

Renderers.html

internal
    • Renderers.html(NDoc)
      • Void

Registers HTML renderer as html.

Example
NDoc.render('html', ast, options, function (err) {
  // ...
});
Options
  • output (String): Directory where to output rendered documentation.
  • title (String): Page title template. You can use {package.*} variables here. Default: '{package.name} {package.version} API documentation'
  • index (String): Intro text.
  • github (String): URL to a project on GitHub. If given, a nice ribbon with link to given URL will be added. You can use {package.*} variables here. Default: Null
  • brokenLinks (show|hide|throw): What to do if broken link occurred. Default: 'show'
class method

Renderers.json

internal
    • Renderers.json(NDoc)
      • Void

Registers JSON renderer as json.

Example
NDoc.render('json', ast, options, function (err) {
  // ...
});
Options
  • output (String): File where to output rendered documentation.
  • title (String): Page title template. You can use {package.*} variables here. Default: '{package.name} {package.version} API documentation'