Neocon Propaganda Machine

    suh-dgeni-ngdocs

    0.8.8 • Public • Published

    suh-dgeni-ngdocs

    A package to generate ngdocs using Dgeni similar to whats currently used on AngularJS website.

    Installation

    Using NPM

     
        npm install suh-dgeni-docs --save-dev
     

    Clone GitHub Reposotiry

     
        git clone https://github.com/suhdev/suh-dgeni-ngdocs 
     

    Usage

    First, install the canonical-path module using NPM, the module is used to generate absolute paths for your source files:

     
        npm install canonical-path --save-dev
     

    Next, create a new javascript file as follows:

     
        var path = require('path'),
            fs = require('fs'),
            ngdocs = require('suh-dgeni-ngdocs');
     
     
        ngdocs.generate({
        defaultDeployment:{
            name:'default',
            meta:{
                description:'just a test',
            },
            navigation:{
                top:{
                    //Navigation items for the top navigation 
                    navItems:[{
                 type:'divider',
               },
               {
                        type:'dropdown',
                        disabled:true,
                        label:'TestModule Documentation',
                        url:'#',
                        menu:[{
                               label:'API Reference',
                               url:'api'
                            },{
                               label:'Guides',
                               url:'guide'
                            },{
                             label:'Suhail',
                             url:'suhail'
                            }
                        ]
               },
               {
               type:'divider'
               }]
                }
            },
            //add any javascript files to be included in the documentation, 
            //usually this includes youre compiled (minimized angular code). 
            //also note that you need to pass the source to the ```path.resolve``` 
            //function to generate the absolute URL. 
            scripts:[path.resolve('./app.min.js')] 
        },
                //base path to your source 
                basePath:path.resolve('testsrc'),
                //add your source paths patterns 
                sourceFiles:[
                    '*.js',
                    '**/*.ngdoc'],
                //still under development, ideally here this will be extracted from code
                //to extract new sections in the documentation other than the predefined ones
                AREA_NAMES:{
                    suhail:'Suhail Abood',
                },
                //define the output path for your documentation
                //again note that we're passing the folder to the 
                //```path.resolve``` function 
                outputFolder:path.resolve('generated'),
                //home page information 
                homePage:{
                    data:{
                        //title of the home page
                        title:'Suhail Abood Library',
                        //desctiption (content of the home page, this can include markdown content as well)
                        //you can pass in the content of the ```README.md``` 
                        description:fs.readFileSync('./README.md').toString(),
                        //still under development, ideally this will be used to add
                        //dependencies section with full details about each dependency. 
                        dependencies:[{
                            name:'angular',
                            version:'1.3.15'
                        },{
                            name:'jquery',
                            version:'2.1.13'
                        }]
                    }
                },
                logger:{
                    //set the ```Dgeni``` logger level (info|warn|debug|error)
                    level:null
                },
                extraData:{
                    //still under development, this object literal is passed on to 
                    //all documents, all partials, and still looking into the potential
                    //usage of such access
                    angular:'1.3.15',
                    jquery:'2.1.13',
                    name:'Suhail Abood',
                    module:{
                        version:'v1.0.0',
                        file:'suhail.js',
                        minifiedFile:'suhail.min.js'
                    }
                }
            });
     

    The same code can be used within a gulp task as follows:

     
    var gulp = require('gulp'); 
     
    //assuming there is a task (```concat-js```) to concatenate the source 
    gulp.task('ngdocs',['concat-js'], function(){
        //wrap in try catch to make sure it doesn't break the flow of task execution 
        //even if it fails. 
        try{
     
        ngdocs.generate({
        defaultDeployment:{
            name:'default',
            meta:{
                description:'just a test',
            },
            navigation:{
                top:{
                    //Navigation items for the top navigation 
                    navItems:[{
                 type:'divider',
               },
               {
                        type:'dropdown',
                        disabled:true,
                        label:'TestModule Documentation',
                        url:'#',
                        menu:[{
                               label:'API Reference',
                               url:'api'
                            },{
                               label:'Guides',
                               url:'guide'
                            },{
                             label:'Suhail',
                             url:'suhail'
                            }
                        ]
               },
               {
               type:'divider'
               }]
                }
            },
            //add any javascript files to be included in the documentation, 
            //usually this includes youre compiled (minimized angular code). 
            //also note that you need to pass the source to the ```path.resolve``` 
            //function to generate the absolute URL. 
            scripts:[path.resolve('./app.min.js')] 
        },
                //base path to your source 
                basePath:path.resolve('testsrc'),
                //add your source paths patterns 
                sourceFiles:[
                    '*.js',
                    '**/*.ngdoc'],
                //still under development, ideally here this will be extracted from code
                //to extract new sections in the documentation other than the predefined ones
                AREA_NAMES:{
                    suhail:'Suhail Abood',
                },
                //define the output path for your documentation
                //again note that we're passing the folder to the 
                //```path.resolve``` function 
                outputFolder:path.resolve('generated'),
                //home page information 
                homePage:{
                    data:{
                        //title of the home page
                        title:'Suhail Abood Library',
                        //desctiption (content of the home page, this can include markdown content as well)
                        //you can pass in the content of the ```README.md``` 
                        description:fs.readFileSync('./README.md').toString(),
                        //still under development, ideally this will be used to add
                        //dependencies section with full details about each dependency. 
                        dependencies:[{
                            name:'angular',
                            version:'1.3.15'
                        },{
                            name:'jquery',
                            version:'2.1.13'
                        }]
                    }
                },
                logger:{
                    //set the ```Dgeni``` logger level (info|warn|debug|error)
                    level:null
                },
                extraData:{
                    //still under development, this object literal is passed on to 
                    //all documents, all partials, and still looking into the potential
                    //usage of such access
                    angular:'1.3.15',
                    jquery:'2.1.13',
                    name:'Suhail Abood',
                    module:{
                        version:'v1.0.0',
                        file:'suhail.js',
                        minifiedFile:'suhail.min.js'
                    }
                }
            }); 
            }catc(err){
                console.log(err);
            }
    });
     

    Custom tags

    1. @todo The tag now supports a type it can be used in the following syntax:

      /** 
       * @ngdoc module
       * @name BlahBlah
       * @module BlahBlah
       * @todo {urgent} this is urgent 
       * @todo {warn} this is not urgent 
       * @todo {urgent} this is also urgent
       * @todo {urgent|next|warn|important|primary|success|danger} {label} todo text
       * @description
       * this is just a description
       */
       

      Also, note that the todo will be grouped by their type and then presented.

      If no type is provided it will default to a primary i.e.

      @todo todo text

    2. @note The tag now supports a type as in the following syntax:

      /** 
       * @ngdoc module
       * @name BlahBlah
       * @module BlahBlah
       * @note {urgent} this is urgent 
       * @note {warn} this is not urgent 
       * @note {urgent} this is also urgent
       * @note {urgent|next|warn|important|primary|success|danger} todo text
       * @description
       * this is just a description
       */
       
    3. @briefdesc This tag allows for adding a special description to show up on summary pages rather than using the first paragraph of the description tag.

      /** 
       * @ngdoc module
       * @name BlahBlah
       * @module BlahBlah
       * @todo {urgent} this is urgent 
       * @todo {warn} this is not urgent 
       * @todo {urgent} this is also urgent
       * @todo {urgent|next|warn|important|primary|success|danger} todo text
       * @description
       * this is just a description
       */
       

    Attribution

    This package is basically an extension to the dgeni-packages module (built on top of it),in which I replaced the templates with customized ones, I've also included some extra tags and extended some of the previously defined ones.

    A full list of the tags will be added here as well as in the documentation (as soon as I finish writing them).

    So, this is to thank everyone who contributed to the dgeni-packages, which can be accessed on dgeni-packages, reading through that code was quiet amusing, and I loved the architecture of the module. It does lack documentation, but the code is almost self explanatory.

    I would also like to thank the guys behind UIKit, which can be accessed on UIKit, as I've used their framework to in the templates (because I suck at design), and I just fall in love with their framework.

    NEXT

    I'm currently working on lots of additions and fixing, however, the base code will not change, and thus the module is ready for usage now, anything else will either be a bug fix or an extension that should be backward compatible. Some of these are:

    1. Using own templates.
    2. Smarter linkage with github and git repository.
    3. Lots of minor bug fixes that I've already noted down.

    I'm compiling a list of the upcoming additions and I'll add them all here as soon as I have a my roadmap ready. Some of these are:

    Suhail Abood

    Install

    npm i suh-dgeni-ngdocs

    DownloadsWeekly Downloads

    29

    Version

    0.8.8

    License

    ISC

    Last publish

    Collaborators

    • suhail