Documenting your Angular code with Docular

This post explains how to create the documentation for your angular code. I tried different solutions including ng-doc and ng-docs but I could not make them work. Finally, I tried docular, and so far, It has been working great.

The following applications and packages were used:

  • Linux Mint 15 (Olivia)
  • Apache 2
  • Angular JS
  • Grunt
  • Docular
  1. Installing Docular

My test project has the following structure:

  • test project
    • code
    • docs

Grunt is required by docular. If you don’t have it yet, you can install it inside your project’s folder (cd ‘test project’). Grunt is installed through NPM running the following command: npm install grunt –save-dev.  The ‘–save-dev’ parameter is optional, it will save this dependency on your package.json file (if any).

After that, run the next command to install docular: npm install grunt-docular –save-dev. Now you have to create the configuration file (Gruntfile.js) with the following information:

module.exports = function(grunt) {
 
    // Project configuration.
    grunt.initConfig({
 
        pkg: grunt.file.readJSON(‘package.json’),
 
        docular: {
            docular_webapp_target : “docs”,
            groups: [],
            showDocularDocs: true,
            showAngularDocs: true
        }
 
    });
 
    // Load the plugin that provides the “docular” tasks.
    grunt.loadNpmTasks(‘grunt-docular’);
 
    // Default task(s).
    grunt.registerTask(‘default’, [‘docular’]);
 
};

I won’t cover the details of this file, but basically you are loading docular and passing basic parameters to it. The docular_webapp_target property shows which folder will be used to store the generated documentation.

From command line, run the following command: grunt

If everything goes fine, the documentation should be stored in your ‘docs’ folder. If you open it in your browser, you might see something like this:

image1

This is because the documentation is not static, but dynamic. And works with Twitter bootstrap and Anjular JS. Hence, these files must be stored in your web server. You can either run a Node JS server or use Apache to host them. If you want to use Apache, just copy those files into your WWW folder.

Now, if you browse http://localhost you should see the following page:

image2

This is the default template provided by Docular. You can either work with this template or write your own.

2. Documenting your code

Docular parses “doc” and “js” files. DOC files provides an overview of your folder or anything else. and JS files are self explanatory. I will cover both of these files for this example. So, let’s start creating a “readme.doc” file inside your code directory with the following information:

@doc overview
@id index
@name Directives
@description Directives are stored in this directory.

Next, lets create a simple JS file called ‘mydirective.js’:

‘use strict’;

/**
 * @ngdoc directive
 * @name myDirective
 * @id directive
 * @description This is a dummy directive.
 *
 * @param {string} apText Sample text.
 *
 * ###Additional information
 * You can write something else if you want.
 */
angular.module(‘directives.mydirective’, [])
    .directive(‘myDirective’, function () {
        return {
            restrict: ‘EA’,
            scope: {
                apText: ‘@’,

            },

            link: function postLink(scope, element, attrs) {
            }
        };
});

There are a lot of tags available to describe your document and you can find them on the Docular site. For this example, I have used the following:

  1. ngdoc.- Type of document.
  2. name.- Name that will be displayed on the page.
  3. id.- Unique id associated to this document.
  4. Description.- Description of this document.
  5. param.- Expected parameters. A document can list more than 1 “param” tag.

Now, we have to go back to our config file (Gruntfile.js) and add the following lines:

module.exports = function(grunt) {
 
    // Project configuration.
    grunt.initConfig({
 
        pkg: grunt.file.readJSON(‘package.json’),
 
        docular: {
            docular_webapp_target : “docs”,
            groups: [
                {
                    groupTitle: ‘My sample project’,
                    groupId: ‘sample’,
                    groupIcon: ‘icon-beer’,
                    sections: [
                        {
                            id: “directives”,
                            title: “Directives”,
                            docs: [“code”],
                            scripts: [
                                “code/mydirective.js”
                            ]
                        }
                    ]
                }
            ],
            showDocularDocs: true,
            showAngularDocs: true
        }
 
    });
 
    // Load the plugin that provides the “docular” tasks.
    grunt.loadNpmTasks(‘grunt-docular’);
 
    // Default task(s).
    grunt.registerTask(‘default’, [‘docular’]);
 
};

A group can be seen as a category. Taking the default template as a reference, the group would be “Docular” and a section is “install docular”. The properties listed on a section are:

  • id.- Section id.
  • title.- Section title, it will be displayed on the page.
  • docs.- relative paths that will be scanned looking for DOC files.
  • scipts.- relative paths that will be scanned looking for JS files.

Now, if you run grunt command again, you should see the following page in your browser:

image3

/directives:

image4

/directives/directive:

image5


Follow

Get every new post delivered to your Inbox.