Dokker.js

Github Pages

JSDoc

Literate programming

Mocha

Utility

Properties

dokker logo

Dokker.js creates professional Javascript code documentations.

See Dokker.js documentation as example.

Build Status

Features

Community

Gitter

Installation

Dokker is available as npm package. So the easiest way is to install dokker as local module into your project:

npm install dokker

Usage

After installation you can execute Dokker with the help of several terminal commands.

Bootstrap Dokker project

Dokker needs a configuration file to execute, such as a .travis or .jshintrc. You can easily create .dokker.json file with the ./node_modules/dokker/bin/init command from the root directory of your project or copy an example file.

Dokker provides a default template for your project. The template is based on an ejs file. Either you use the default template or modify it. If you choose for the latter you can copy the templates directory and tweak the ejs files how you like.

Create documentation

Creating a documentation is really simple with the help of Dokker. You just configure the .dokker.json file and execute ./node_modules/dokker/bin/dokker. Then you’re done.

Live edit your documentation

If you want to work on your source file and see how the documentation evolves, you can do ./node_modules/dokker/bin/watch and it will open a browser with live preview.

Deploy to Github Pages

If you want to deploy your documentation to Github Pages, run ./node_modules/dokker/bin/gh-pages. Finally a separate branch, named gh-pages is created from the docs folder. That is enough for Github to serve your documentation. Please do not forget to git commit your changes before your run gh-pages command.

Dokker in the wild

Some examples by our users. Let us know what you did with Dokker too!

Further Reading

Contributors

API documentation

“Github Pages” Methods

Dokker.ghPages()

# Ⓢ [Ⓣ][1]

Runs a terminal shell with the git command to extract the docs branch into a seperate gh-pages branch and finally pushes that branch to Github, so that the Github page is updated.

Returns

(Promise): Returns a resolved promise if file was created.

Example

Dokker.ghPages()
.then(function(){
  // => resolved promise
});

“JSDoc” Methods

Dokker.injectTemplate([options])

# Ⓢ [Ⓣ][1]

Creates a HTML file that transcludes the HTML snippet that was created by the docdown module into an ejs template which is defined by the .dokker.json configuration file.

Arguments

  1. [options] (Object): The options object.
  2. [options.template='template/index.ejs.html'] (String): The path to the ejs template file.
  3. [options.html='docs/index.html'] (string): The path to the docdown generated JSDoc documentation.
  4. [options.readme='README.md'] (string): The path to the README.md file.
  5. [options.title=''] (string): The title for the documentation.

Returns

(Promise): Returns a resolved promise if file was created.

Example

var options = {
  template: 'template/index.ejs.html',
  html: 'docs/index.html',
  readme: 'docs/README.md',
  title: 'Dokker.js API Documentation'
};
Dokker.injectTemplate(options)
.then(function(){
  // => resolved promise
});

Dokker.jsdocHtml([options])

# Ⓢ [Ⓣ][1]

Create an HTML file from the Markdown file that was create with Dokker.jsdocMarkdown()

Arguments

  1. [options] (Object): The options object.
  2. [options.markdown='docs/READMDE.md'] (string): The path where to save the Markdown file.

Returns

(Promise): Returns a resolved promise if file was created.

Example

var options = {
  markdown: 'docs/README.md'
};
Dokker.jsdocHtml()
.then(function(){
  // => resolved promise
});

Dokker.jsdocMarkdown([options])

# Ⓢ [Ⓣ][1]

Create a Markdown file from JSDoc tags.

Arguments

  1. [options] (Object): The options object.
  2. [options.source='app.js'] (String): The path the source code with JSDoc tags.
  3. [options.github =''] (String): The path the Github repository.
  4. [options.markdown='docs/READMDE.md'] (string): The path where to save the Markdown file.

Returns

(Promise): Returns a resolved promise if file was created.

Example

var options = {
  source: 'app.js',
  markdown: 'docs/README.md'
};
Dokker.jsdocMarkdown()
.then(function(){
  // => resolved promise
});

“Literate programming” Methods

Dokker.literate([options])

# Ⓢ [Ⓣ][1]

Create a styled HTML file from your source code with the help of docco module.

Arguments

  1. [options] (Object): The options object.
  2. [options.source='app.js'] (String): The path the source code with comments
  3. [options.dir='docs/annotated'] (string): The directory where to save the generated HTML file.

Returns

(Promise): Returns a resolved promise if file was created.

Example

var options = {
  dir: 'docs',
  source: 'app.js'
};
Dokker.literate()
.then(function(){
  // => resolved promise
});

“Mocha” Methods

Dokker.createTests([options])

# Ⓢ [Ⓣ][1]

Creates an HTML file to describe the features of your module from your Mocha tests. The module is using the mocha doc reporter to generate the HTML contents.

Arguments

  1. [options] (Object): The options object.
  2. [options.path='docs.html'] (String): The path where to save the HTML file

Returns

(Promise): Returns a resolved promise if file was created.

Example

var options = {
  path: 'docs/tests.html',
};
Dokker.createTests(options)
.then(function(){
  // => resolved promise
});

“Utility” Methods

Dokker.configure([options])

# Ⓢ [Ⓣ][1]

Helper function that takes a couple of options arguments and normalises them and subsequently returns them.

Arguments

  1. [options] (Object): The options object.
  2. [options.li.markdown='docs/READMDE.md'] (string): The path where to
  3. [options.source='app.js'] (String): The path the source code with JSDoc tags.
  4. [options.jsdoc.markdown='docs/READMDE.md'] (string): The path where to save the Markdown file.
  5. [options.jsdoc.README ='READMDE.md'] (string): The path to the project’s README.md file
  6. [options.jsodc.template ='templates/index.ejs.html'] (String): The path to the ejs template.
  7. [options.mocha.template='templates/tests.ejs.html'] (String): The path to the mocha template.
  8. [options.dir='docs'] (String): The path where to store the generated files

Returns

(Promise): Returns a resolved promise with edited options object

Example

var options = {
  dir: 'docs',
  literate: {
    source: 'dokker.js',
    dir: 'annotated'
  },
  jsdoc: {
    title: 'Dokker.js',
    source: 'dokker.js',
    markdown: 'README.md',
    html: 'index.html',
    readme: 'README.md',
  }
};
Dokker.jsdocHtml()
.then(function(){
  // => object with absolute pathes to the directory from
  // which the command was executed
});

Dokker.copyTemplate([options])

# Ⓢ [Ⓣ][1]

Copy the template to local directory so that one can make changes to ejs files.

Arguments

  1. [options] (Object): The options object.
  2. [options.dir='templates'] (string): The path where to save the template files

Returns

(Promise): Returns a resolved promise if files were created.

Example

var options = {
  dir: 'template'
};
Dokker.copyTemplate()
.then(function(){
  // => resolved promise
});

Dokker.init()

# Ⓢ [Ⓣ][1]

Create a .dokker.json file to bootstrap any Dokker project

Returns

(Promise): Returns a resolved promise if files were created.

Example

Dokker.init()
.then(function(){
  // => resolved promise
});

Dokker.watch()

# Ⓢ [Ⓣ][1]

Starts a Node.js/Express webserver in docs directory to watch the build Dokker project

Returns

(Promise): Returns a resolved promise if files were created.

Example

Dokker.init()
.then(function(){
  // => resolved promise
});

Properties

Dokker.VERSION

# Ⓢ [Ⓣ][1]

(string): The semantic version number.