Have ideas to improve npm?Join in the discussion! »

    generator-ngdoc

    0.1.6 • Public • Published

    generator-ngdoc npm Build Status

    This is a Yeoman generator for documentation of AngularJS modules.

    This generator scaffolds:

    /**
     *
     * @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
    

    License

    MIT

    Install

    npm i generator-ngdoc

    DownloadsWeekly Downloads

    46

    Version

    0.1.6

    License

    MIT

    Last publish

    Collaborators

    • avatar