Documenting your Angular app using Dgeni in 10 easy steps

├── docs/
│   ├── app/
│   ├── config/
│   │  ├── processors/
│   │  ├── templates/
│   │  ├── index.js
│   ├── content/

var path = require('canonical-path');
var packagePath = __dirname;

var Package = require('dgeni').Package;

// Create and export a new Dgeni package
// We will use Gulp later on to generate that package
// Think of packages as containers, our 'myDoc' package contains other packages
// which themselves include processors, services, templates...
module.exports = new Package('myDoc', [
  require('dgeni-packages/ngdoc'),
  require('dgeni-packages/nunjucks'),
]);

.config(function(log, readFilesProcessor, writeFilesProcessor) {

    // Set the log level to 'info', switch to 'debug' when troubleshooting
    log.level = 'info';

    // Specify the base path used when resolving relative paths to source and output files
    readFilesProcessor.basePath = path.resolve(packagePath, '../..');

    // Specify our source files that we want to extract
    readFilesProcessor.sourceFiles = [
        { include: 'src/app/**/**/*.js', basePath: 'src/app' }, // All of our application files
    ];

    // Use the writeFilesProcessor to specify the output folder for the extracted files
    writeFilesProcessor.outputFolder = 'docs/build';

})

.config(function(templateFinder) {
  // Specify where the templates are located
  templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates'));
})

.config(function(computePathsProcessor) {

    // Here we are defining what to output for our docType Module
    //
    // Each angular module will be extracted to it's own partial
    // and will act as a container for the various Components, Controllers, Services in that Module
    // We are basically specifying where we want the output files to be located
    computePathsProcessor.pathTemplates.push({
        docTypes: ['module'],
        pathTemplate: '${area}/${name}',
        outputPathTemplate: 'partials/${area}/${name}.html'
    });

    // Doing the same thing but for regular types like Services, Controllers, etc...
    // By default they are grouped in a componentGroup and processed
    // via the generateComponentGroupsProcessor internally in Dgeni
    computePathsProcessor.pathTemplates.push({
        docTypes: ['componentGroup'],
        pathTemplate: '${area}/${moduleName}/${groupType}',
        outputPathTemplate: 'partials/${area}/${moduleName}/${groupType}.html'
    });

})

// Remember the sourceFiles section we added earlier? Let's now add our .md file to the list !
readFilesProcessor.sourceFiles = [
  { include: 'src/app/**/**/*.js', basePath: 'src/app' }, // All of our application files

  // Our static Markdown documents
  // We are specifying the path and telling Dgeni to use the ngdocFileReader
  // to parse the Markdown files to HTMLs
  {
    include: 'docs/content/**/*.md',
    basePath: 'docs/content',
    fileReader: 'ngdocFileReader',
  },
];

// create new compute for 'content' type doc
// indexPage is something new we will be defining later
computeIdsProcessor.idTemplates.push({
  docTypes: ['content', 'indexPage'],
  getId: function(doc) {
    return doc.fileInfo.baseName;
  },
  getAliases: function(doc) {
    return [doc.id];
  },
});

// Document this part a little bit more?

// Build custom paths and set the outputPaths for "content" pages
computePathsProcessor.pathTemplates.push({
  docTypes: ['content'],
  getPath: function(doc) {
    var docPath = path.dirname(doc.fileInfo.relativePath);
    if (doc.fileInfo.baseName !== 'index') {
      docPath = path.join(docPath, doc.fileInfo.baseName);
    }
    return docPath;
  },
  outputPathTemplate: 'partials/${path}.html',
});

var Dgeni = require('dgeni');

gulp.task('dgeni', function() {
  // Notice how we are specifying which config to use
  // This will import the index.js from the /docs/config folder and will use that
  // configuration file while generating the documentation
  var dgeni = new Dgeni([require('./docs/config')]);

  // Using the dgeni.generate() method
  return dgeni.generate();
});

// app.module.js
// Creating the root app module
angular.module('docs', ['ui.router']);

// app.config.js
// HTML5Mode to true, adding that config block to our root app module
angular.module('docs').config(config);

function config($locationProvider) {
  // Set HTML5 Mode
  $locationProvider.html5Mode(true);

  // Later on we will define our states
}
config.$inject = ['$locationProvider'];

// api.js
angular.module('docs').controller('ApiController', ApiController);

function ApiController() {
  var ctrl = this;
}
ApiController.$inject = [''];

// guide.js
angular.module('docs').controller('GuideController', GuideController);

function GuideController() {
  var ctrl = this;
}
GuideController.$inject = [''];

module.exports = function indexPageProcessor() {
  return {
    $runAfter: ['adding-extra-docs'],
    $runBefore: ['extra-docs-added'],
    $process: process,
  };

  function process(docs) {
    // Document what this does? pushes to the docs obj the props
    docs.push({
      docType: 'indexPage',
      template: 'indexPage.template.html',
      outputPath: 'index.html',
      path: 'index.html',
      id: 'index',
    });
  }
};

// /docs/config/index.js
.processor(require('./processors/index-page'))

angular
  // Injecting into our app module
  .module('docs')

  // Creating an Angular constant and rendering a list of items as JSON
  .constant('{$ doc.name $}', {$ doc.items | json $});

// processors/api-data.js

var _ = require('lodash');

// Creating a generic method to assign all of our
// data more easily (including subpages)
function buildDocData(doc, extraData) {
  // So that we can create states even though our module names contain dots(.)
  // in UI-Router dotted notation means it's a child state, so this is problematic
  // if we are following Angular styleguides and conventions regarding
  // naming of our Modules
  // #hack #lazy
  var splitName = doc.name.split('.');
  doc.stateName = _.camelCase(splitName);

  return _.assign(
    {
      name: doc.name,
      stateName: doc.stateName,
      type: doc.docType,
      outputPath: doc.outputPath,
      url: doc.path,
    },
    extraData
  );
}

module.exports = function apiPagesProcessor(moduleMap) {
  // Defining when the processor will run, and it's process
  return {
    $runAfter: ['paths-computed'],
    $runBefore: ['rendering-docs'],
    $process: process,
  };

  // Our process method definition
  // Getting all docs as a parameter
  function process(docs) {
    var apiPages = _(docs)
      // Filtering our all the docs that are not in a module
      // and the ones that are componentGroups
      .filter(function(doc) {
        return doc.docType !== 'componentGroup';
      })

      // Filtering and grouping by Module
      .filter('module')
      .groupBy('module')

      // Map of our Module Docs
      .map(function(moduleDocs, moduleName) {
        var moduleDoc = _.find(docs, {
          docType: 'module',
          name: moduleName,
        });

        // Making sure we don't get any exceptions when the module is undefined
        if (!moduleDoc) return;

        // Calling back to our generic method to build the object
        return buildDocData(moduleDoc, {
          docs: moduleDocs

            .filter(function(doc) {
              return doc.docType !== 'module';
            })

            .map(buildDocData),
        });
      })

      // Removing null items
      .filter()

      // Get the value
      .value();

    // After all the processing is done, we push the changes to docs
    // Note here that we are using our constant template defined earlier
    // Name and Items are parsed with the template
    docs.push({
      name: 'API_DATA',
      template: 'constant-data.template.js',
      outputPath: 'src/api-data.js',
      items: apiPages,
    });
  }
};

// processors/guide-data.js

var _ = require('lodash');

// Once again, simple generic method to assign all our data
function buildDocData(doc) {
  return _.assign({
    name: doc.name,
    type: doc.docType,
    outputPath: doc.outputPath,
    url: doc.path,
  });
}

module.exports = function guidePagesProcessor(moduleMap) {
  return {
    $runAfter: ['paths-computed'],
    $runBefore: ['rendering-docs'],
    $process: process,
  };

  function process(docs) {
    // Filtering out to get only 'content' types and
    // only the ones under the 'guide' module
    var guides = _(docs)
      .filter(function(doc) {
        return doc.docType === 'content' && doc.module === 'guide';
      })

      // Sort them via the path, you could also add a sortOrder param
      .sortBy(function(page) {
        return page.path;
      })

      // Mapping them with our generic method
      .map(buildDocData)

      // Get the value
      .value();

    // Using the same constant template but using a different
    // name and file path
    docs.push({
      name: 'GUIDE_DATA',
      template: 'constant-data.template.js',
      outputPath: 'src/guide-data.js',
      items: guides,
    });
  }
};

// /docs/config/index.js

// Already existed
.processor(require('./processors/index-page'))

// Let's add our API and Guide processors
.processor(require('./processors/guide-data'))
.processor(require('./processors/api-data'))

// app/api.js
function ApiController(API_DATA) {
  var ctrl = this;
  ctrl.allPages = API_DATA;
}
ApiController.$inject = ['API_DATA'];

// app/guide.js
function GuideController(GUIDE_DATA) {
  var ctrl = this;
  ctrl.allPages = GUIDE_DATA;
}
GuideController.$inject = ['GUIDE_DATA'];

// app.config.js
function config(
  $locationProvider,
  $stateProvider,
  API_DATA,
  GUIDE_DATA,
  $urlRouterProvider
) {
  // Set HTML5 Mode
  $locationProvider.html5Mode(true);

  // Configure URL Router to redirect to /api
  // if state doesn't exist
  $urlRouterProvider.otherwise('/api');

  // Defining our template for the sidebar
  // Could've been in a partial, but it's simple
  // enough that it can be a string template
  var sidebarTemplate =
    '<h4>Contents</h4>' +
    '<ol class="list-unstyled">' +
      '<li ng-repeat="page in ctrl.allPages">' +
        '<a href="{{ page.url }}">{{ page.name }}</a>' +
        '<ol class="list-unstyled" style="padding-left: 15px;">' +
          '<li ng-repeat="child in page.docs">' +
            '<a href="{{ child.url }}">{{ child.name }}</a>' +
          '</li>' +
        '</ol>' +
      '</li>' +
    '</ol>';

  // Assign our root state for API pages to var
  // Assigning the basepage as the partials
  // Setup the sidebar to use our ApiController and template
  var apiState = {
    name: 'api',
    url: '/api',
    views: {
      main: {
        templateUrl: 'partials/api.html',
      },
      sidebar: {
        template: sidebarTemplate,
        controller: 'ApiController as ctrl',
      },
    },
  };

  // Same thing for our guide page
  var guideState = {
    name: 'guide',
    url: '/guide',
    views: {
      main: {
        templateUrl: 'partials/guide.html',
      },
      sidebar: {
        template: sidebarTemplate,
        controller: 'GuideController as ctrl',
      },
    },
  };

  // Using the $stateProvider from UI-Router
  // to create the states in the application
  $stateProvider.state(apiState);
  $stateProvider.state(guideState);

  // Looping through all of our API pages
  // and dynamically creating new states based
  // on the data generated by Dgeni
  angular.forEach(API_DATA, function(parent) {
    var newState = {
      name: parent.name,
      url: '/' + parent.url,
      views: {
        main: {
          templateUrl: parent.outputPath,
        },
        sidebar: {
          template: sidebarTemplate,
          controller: 'ApiController as ctrl',
        },
      },
    };

    // Creating the states using $stateProvider
    $stateProvider.state(newState);

    // In the case of API, we have multiple modules and each
    // of them have children, so we are doing the same thing
    // here but for the child states
    angular.forEach(parent.docs, function(doc) {
      var newState = {
        name: doc.name,
        url: '/' + doc.url,
        views: {
          main: {
            templateUrl: doc.outputPath,
          },
          sidebar: {
            template: sidebarTemplate,
            controller: 'ApiController as ctrl',
          },
        },
      };

      // Creating the states using $stateProvider
      $stateProvider.state(newState);
    });
  });

  // Same thing for Guide, except in this case we only
  // have 'root' pages, so no need to loop twice
  angular.forEach(GUIDE_DATA, function(parent) {
    var newState = {
      name: parent.name,
      url: '/' + parent.url,
      views: {
        main: {
          templateUrl: parent.outputPath,
        },
        sidebar: {
          template: sidebarTemplate,
          controller: 'GuideController as ctrl',
        },
      },
    };

    // Creating the states using $stateProvider
    $stateProvider.state(newState);
  });
}
config.$inject = [
  '$locationProvider',
  '$stateProvider',
  'API_DATA',
  'GUIDE_DATA',
  '$urlRouterProvider',
];

/**
 *
 * @ngdoc module
 * @name components.contact
 *
 * @requires ui.router
 *
 * @description
 *
 * This is the contact module. It includes all of our components for the contact feature.
 * ## This also parses down Markdown
 *
 * - So you can add lists
 * - List 2
 *
 * ###And regular paragraph and headlines
 *
 **/

/**
 * @ngdoc method
 * @name ContactEditController#updateContact
 *
 * @param {event} event Receive the emitted event
 * Updates the contact information
 *
 * @return {method} ContactService returns the updateContact method and a promise
 */

/**
 * @ngdoc service
 * @name ContactService
 * @module components.contact
 *
 * @description Provides HTTP methods for our firebase connection.
 *
 * ## Lorem Ipsum 1
 * Aenean ornare odio elit, eget facilisis ipsum molestie ac. Nam bibendum a nibh ut ullamcorper.
 * Donec non felis gravida, rutrum ante mattis, sagittis urna. Sed quam quam, facilisis vel cursus at.
 *
 * ## Lorem Ipsum 2
 * Aenean ornare odio elit, eget facilisis ipsum molestie ac. Nam bibendum a nibh ut ullamcorper.
 * Donec non felis gravida, rutrum ante mattis, sagittis urna. Sed quam quam, facilisis vel cursus at.
 */

/**
 * @ngdoc type
 * @module components.contact
 * @name ContactEditController
 *
 * @description
 *
 * ## Lorem Ipsum 1
 * Aenean ornare odio elit, eget facilisis ipsum molestie ac. Nam bibendum a nibh ut ullamcorper.
 * Donec non felis gravida, rutrum ante mattis, sagittis urna. Sed quam quam, facilisis vel cursus at.
 *
 * ## Lorem Ipsum 2
 * Aenean ornare odio elit, eget facilisis ipsum molestie ac. Nam bibendum a nibh ut ullamcorper.
 * Donec non felis gravida, rutrum ante mattis, sagittis urna. Sed quam quam, facilisis vel cursus at.
 */

/**
 * @ngdoc directive
 * @name lengthCheck
 * @module components.contact
 *
 * @description
 *
 * Aenean ornare odio elit, eget facilisis ipsum molestie ac. Nam bibendum a nibh ut ullamcorper.
 * Donec non felis gravida, rutrum ante mattis, sagittis urna. Sed quam quam, facilisis vel cursus at.
 *
 * @usage
 *
 * ### How to use
 * Aenean ornare odio elit, eget facilisis ipsum molestie ac. Nam bibendum a nibh ut ullamcorper.
 * Donec non felis gravida, rutrum ante mattis, sagittis urna. Sed quam quam, facilisis vel cursus at.
 **/