Generator-ngdoc NPM

generator-ngdoc

This is a Yeoman generator for documentation of AngularJS modules.

This generator scaffolds:

a WebApp like AngularJS document's site
gulp tasks to process ngDoc annotations in your JavaScript codes such as:

/**
 *
 * @ngdoc directive
 * @name awesomeElement
 * @module myModule
 * @restrict E
 * @descrition
 * This is an awesome directive!
 *
**/
angular.module('myModule')
  .directive('awesomeElement', function () {
    return {
      // Derective definision...
    };
  });

Why?

As the originator, I want to write documents of my AngualrJS module in ngdoc notation and to publish them as a web application.

I choose Dgeni and dgeni-packages as the ngdoc processor. These packages generate partial html contents of api, they don't generate an application that integrate these partial pages.

So, this generator scaffolds not only Dgeni configurations but also an application of documents.

Demo site

Here is a demo site generated with this generator.

Usage

To install yeoman and generator-dgeni from npm, run:

npm install -g yo generator-ngdoc

Create a project directory and change the current directory.

mkdir my-anguar-module
cd my-angular-module

Initiate the generator:

yo ngdoc

Change the current to docs directory:

cd docs

Run gulp task:

gulp docs:serve

A web application of documentation starts in your browser.

I already have a module project, can I use this generator?

No problem. This generator is designed for adding onto existing projects.

Almost all of the files are created under only docs directory (see also directory structure).

If you have a project(e.g. your-module) which was generated by other generator(e.g. generator-gulp-angular):

cd your-module
yo ngdoc
cd docs
gulp docs:serve

If necessary, you can modify the settings for the location of source files. By default, the gulp task searchs source files from src/**/*.js

docs/gulp/dgeni.js

    var dgeni = new Dgeni([require('../config/')
      .config(function (readFilesProcessor, writeFilesProcessor) {
        //
        
        // Specify collections of source files that should contain the documentation to extract
        readFilesProcessor.sourceFiles = [{include: 'src/**/*.js', basePath: 'src'}, {include: 'docs/content/**/*.ngdoc',basePath: 'docs/content'}];

        //
      })
      :

Gulp Tasks

You should run any gulp tasks generated by generator-ngdoc in 'docs' directory.

cd docs

`docs:serve`

Generate ngdoc and run document application on Node.js server.

gulp docs:serve

This task watches your JavaScript source files. If you modify these files, re-generate ngdocs and reload browser.

`docs:build`

Build document application package, and place in directory 'docs/dist'.

gulp docs:build

You can use this task for publishing the document application.

`docs:serve:dist`

Run document application package created by docs:build task on Node.js web server.

gulp docs:serve:dist

Directory structure

├──  src/                         Put your source files in this dir
│   └──  components/
│        ├──  sample/             Sample components's source files generated by generator-ngdoc
│        └──  index.js            Module definition is written in this
│
├──  docs/                        Sub dir for documentation
│   ├──  .tmp/                    
│   ├──  app/                     Documentation app root directory
│   │   ├──  src/
│   │   ├──  styles/
│   │   └──  index.html
│   ├──  bower_components/
│   ├──  config/                  Dgeni configurations
│   │   ├──  processors/
│   │   ├──  templates/
│   │   └──  index.js
│   ├──  content/                 Additional documentation sources
│   │   ├──  guide/
│   │   ├──  api.ngdoc
│   │   ├──  guide.ngdoc
│   │   └──  index.ngdoc
│   ├──  dist/                    The destination directory of the gulp task 'docs:build'
│   ├──  gulp/                    Definition of gulp tasks
│   ├──  lib/                     Misc node modules
│   ├──  node_modules/
│   ├──  bower.json               Bower configuration for documentation app
│   ├──  gulpfile.js
│   └──  package.json             Node configuration to build documentation app
│
├──  .gitignore
├──  bower_components/
└──  bower.json                   Bower configuration for your modules