vertafore / grunt-docular Goto Github PK

I am trying to document a directive that has a couple complex properties on it. Because of this I am using a controller just like angular.js does it in their documentation. Adding this tag causes all kinds or problems when the documentation is generated. Here is result:

My code looks like this. Am I doing something wrong? I have tried everything short of banging my head against the wall:

Two exceptions are thrown from this:

1. Unterminated string constant
2. Argument '"Controller"' is not a function...

First off, great work putting together what you've done so far.

1. Is there an easy way to extract the template that grunt-docular uses and point it to use a different directory? Right now I've just been using the built in templates and when I want to add/remove css or js files I modify the templates inside of the node_modules directory. This works great for me but as I want to use this on a few projects here at work it will not work because I don't want everyone to have to make these changes.
2. Somewhat related to my first question, is there a built in way to link built files in my current to the generated docs? I have a set of directives that I'm generating this documentation for and right now I'm outputting 2 files. One in my /dist directory and another in the /node_modules directory where the file server is ran. Ideally I'd be able to include files from my root workspace. It also appears the directives that I've written aren't being executed on my example code but I think its related to how I'm linking them on the page and I need to add my angular module to the code that is executed on the docs page.
3. Last question. If either of the things I've asked above can be fixed by a code change then point me in the right direction and I'll try to help out. Just thought I'd check first to see if there was a configuration change I could do.

Again, great project. My project is a set of directives to help jQuery Mobile components work better with Angular. So the complexity is a little higher since I need to load jQM on the page, then, these angular directives, then get them to run.

Thanks.

Just a basic service file in an angular application.

When creating a service file, the documentation group shows up, but only shows the functions on the page if you change the search filter. Seems like it could be a default filter value, or an ng-pristine issue. I will look into it to see if I get fix it or get soem more information.

grunt-docular seems to exit the build as soon as it is finished. if you use it in a list of tasks, anything after it in the list is not executed. is this by design?

Hi,

The documentation is not up to date regarding scripts and docssections attributes.
You need to figure out why it's not working by going to the docular git.

And therefore the files should be auto expanded, using grunt.file.expand(), if a string is passed as the files attributes, which should be always the case :)

Most of my applications modules have periods in their names. so if I have a module called a.b and do my documentation like a.b.directives:directiveName then it is not parsed correctly. It parses it as a then section b. Is there a way I can keep my modules named the same but have it parsed correctly?

I keep getting this error:

(node) warning: Recursive process.nextTick detected. This will break in the next version of node. Please use setImmediate for recursive deferral.

node.js:0
// Copyright Joyent, Inc. and other Node contributors.
^
RangeError: Maximum call stack size exceeded

When trying to generate documentation. My config:

"docular":{
        "baseUrl":"http://127.0.0.1:9001",
        "showAngularDocs":true,
        "docular_webapp_target":"docs",
        "groups":[
            {
                "groupTitle":"{%=name%}",
                "groupId":"{%=sterileName%}",
                "sections":[
                    {
                        "id":"{%=name%}",
                        "title": "{%=name%} App",
                        "scripts":[
                            "src/js/"
                        ],
                        "docs":[
                            "README.md"
                        ]
                    }
                ]
            }
        ]
    }

I don't have any tags set up yet, not sure if that would matter. THanks

The grunt task does not seem to work with the load-grunt-config task, which lets you split grunt configurations into separate files.

Looking at the tasks/docular.js file I can see that configuration is fetched using grunt.config('docular'), unlike many other tasks which are using the this.options() syntax. Maybe using the latter would make it compatible?

Hi, some of my directives require glyphicons. Is it possible to tell docular to move over my font files along with the css?

Hi,

I'm trying to use grunt-docular on a simple AngularJS application, I could get grunt-docular to run and generate documents.

I need to setup a separate web server just to view the doc since docular-server not worked for me.

I keep getting currentPage is null exception in browser console when I tried to click on any sections.

When I typed something in filter box, only at that time I saw my module/controllers...etc, clicked on them would generate a blank page, and a 404 in console, please have a look at the attached image.

Please help, I don't know where I got it wrong. Tried to read the documents multiple times, couldn't find what's wrong...

Here's my setup:

        docular: {
            docular_webapp_target: 'docs',
            groups: [{
                groupTitle: 'OTCS Angular POC',
                groupId: 'myApp',
                groupIcon: 'icon-book',
                sections: [
                    {
                        id: 'app',
                        title: 'Main Application',
                        scripts: ['app/js/modules/app.js']
                    },
                    {
                        id: 'controllers',
                        title: 'Controllers',
                        scripts: ['app/js/modules/controllers.js']
                    }
                ]
            }],
            showDocularDocs: false,
            showAngularDocs: false
        },

here's the comments in the app.js file

/**
 * @doc overview
 * @id app
 * @name OTCS Angular POC Application
 * @description The application was just a POC, written with AngularJS
 */

'use strict';

/**
 * @doc module
 * @name Application
 * @description The application module is just a main entry point of the application, declaring dependencies on other modules
 */
angular.module('my-app', []);

'use strict';

/**
 * @doc module
 * @name controllers
 * @description
 *
 * ## Controllers
 *
 * Controllers of the applications
 */
angular.module('controllers', ['services', 'ui.bootstrap'])

    /**
     * @ngdoc controller
     * @name controllers.controller:LoginController
     *
     * @description
     * LoginController takes care of the login process
     */
    .controller('LoginController', ['$scope', '$location', function ($scope, $location) {
       ...
    }])

    /**
     * @ngdoc controller
     * @name controllers.controller:ToolboxController
     *
     * @description
     * ToolboxController takes care of the left toolbox
     */
    .controller('ToolboxController', ['$scope', function ($scope) {
    }])

    /**
     * @ngdoc controller
     * @name controllers.controller:CreateObjectController
     *
     * @description
     * CreateObjectController is the controller to create new items
     */
    .controller('CreateObjectController', ['$scope', '$rootScope', '$location', '$modal', function ($scope, $rootScope, $location, $modal) {
     }]);

I'm trying to run some of the examples using 0.2.4 version of grunt-docular. When I use the @doc annotation, nothing gets generated, but if I use @ngdoc, then it works just fine. Here are two examples I'm trying to run. First one has no documentation generated, second works just fine.

/**
 * @doc module
 * @id docular
 * @todo foobar
 * @description This module contains all the logic for the workflow of generating
 * partials and front end resources for display of docular documentation.
 *
 * Based off of Angular.js original implementation of gen-docs.js
 * Documentation code licensed under CC BY 3.0
 * http://creativecommons.org/licenses/by/3.0/
 */

/**
 * @ngdoc module
 * @id docular
 * @todo foobar
 * @description This module contains all the logic for the workflow of generating
 * partials and front end resources for display of docular documentation.
 *
 * Based off of Angular.js original implementation of gen-docs.js
 * Documentation code licensed under CC BY 3.0
 * http://creativecommons.org/licenses/by/3.0/
 */

My grunt config:

docular: {
      useHtml5Mode: false,
      docular_webapp_target : 'docs',
      groupTitle: 'App Test Docs',
      examples: {},
      groups: [
        {
          groupTitle: 'App Test Group',
          groupId: 'apptestgroup',
          groupIcon: 'book',
          sections: [
            {
              id: 'apptest',
              title: 'App Test',
              scripts: [
                'app.js'
              ],
            },
          ],
        },
      ],
    },

Below is my terminal output. It appears to spit out code but I can't find where:

-------- verifying plugins --------
-------- generating Docs --------
Extracting docular Docs For Section "docularinstall"...
Extracting docular Docs For Section "docularinstall"...
Extracting docular Docs For Section "docularconfigure"...
Extracting docular Docs For Section "docularcreate"...
Extracting docular Docs For Section "embed"...
Extracting docular Docs For Section "basics"...
Extracting docular Docs For Section "doctypes"...
Extracting docular Docs For Section "docularext"...
Extracting docular Docs For Section "docular"...
Extracting docular Docs For Section "sublime"...
Extracting docular Docs For Section "docularfaq"...
Extracting example Docs For Section "globals"...
Extracting example Docs For Section "doctypes"...
Extracting angular Docs For Section "api"...
Extracting angular Docs For Section "guide"...
Extracting angular Docs For Section "tutorial"...
Extracting angular Docs For Section "misc"...
-------- generating partials directories for groups --------
-------- generating partials directories for sections --------
-------- merging child docs with parent docs --------
BAD LINK: documentation/angular/cookbook/index
BAD LINK: documentation/docular/basics/booyah
-------- generating partials --------
-------- generating supporting files --------
-------- generating index.html page --------
-------- gathering all doc_api, plugin, and configured css and js --------
-------- generating report --------
DONE! Generated 283 pages in 4786 ms. Partials per second : 59

It would be helpful to be able to specify a port when running docular-server. PR coming soon...

When docular includes the ability to install a new docAPI (probably as an npm package), then we need to add an installDocAPI task so that it can get installed by docular and put into the right place.

That issue is being tracked here: Vertafore/docular#2

Hi stephen.
I think it would be a good idea to move docular server from docular to grunt-docular to allow docular to concentrate on documentation generation.
I'll be happy to create the appropriate task and create a pull request.

let me know if you're interested

When I run

grunt docularserver

I see the following error message:

Warning: Arguments to path.join must be strings Use --force to continue.

What am I doing wrong?

using docular with AngularJS and @ngdoc produces two entries foreach directive/service/filter even with example code from here: http://grunt-docular.com/documentation/example/doctypes/doctypes_ngdoc.service:service_example

if I try to generate any dummy documentation, then I cannot get docular to write out the actual documentations content. Even if I turn on

showDocularDocs: true, 
showAngularDocs: true

it's still not working correctly.

https://github.com/burib/grunt-docular.example

please advice.

Can't start ducular server, it say that it can't find server configs, where to get them?

Failed to load server configs { [Error: Cannot find module '/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/lib/nodeserver/configs/configs.js'] code: 'MODULE_NOT_FOUND' }
 { [Error: Command failed: connect.multipart() will be removed in connect 3.0
visit https://github.com/senchalabs/connect/wiki/Connect-3.0 for alternatives
connect.limit() will be removed in connect 3.0

events.js:71
        throw arguments[1]; // Unhandled 'error' event
                       ^
Error: listen EADDRINUSE
    at errnoException (net.js:770:11)
    at Server._listen2 (net.js:910:14)
    at listen (net.js:937:10)
    at Server.listen (net.js:986:5)
    at Function.app.listen (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/express/lib/application.js:533:24)
    at main (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/lib/nodeserver/server.js:131:9)
    at /home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/lib/nodeserver/server.js:168:5
    at _fulfilled (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/q/q.js:797:54)
    at Promise.then.self.promiseDispatch.done (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/q/q.js:826:30)
    at Promise.promise.promiseDispatch (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/q/q.js:759:13)
] killed: false, code: 1, signal: null } connect.multipart() will be removed in connect 3.0
visit https://github.com/senchalabs/connect/wiki/Connect-3.0 for alternatives
connect.limit() will be removed in connect 3.0

events.js:71
        throw arguments[1]; // Unhandled 'error' event
                       ^
Error: listen EADDRINUSE
    at errnoException (net.js:770:11)
    at Server._listen2 (net.js:910:14)
    at listen (net.js:937:10)
    at Server.listen (net.js:986:5)
    at Function.app.listen (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/express/lib/application.js:533:24)
    at main (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/lib/nodeserver/server.js:131:9)
    at /home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/lib/nodeserver/server.js:168:5
    at _fulfilled (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/q/q.js:797:54)
    at Promise.then.self.promiseDispatch.done (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/q/q.js:826:30)
    at Promise.promise.promiseDispatch (/home/set/www/gtdl/node_modules/grunt-docular/node_modules/docular/node_modules/q/q.js:759:13)

and here is my Grunt.js:

module.exports = function(grunt) {

  // Project configuration
  grunt.initConfig({

    pkg: grunt.file.readJSON('package.json'),

    docular: {
      baseUrl: '/', //base tag used by Angular
      showAngularDocs: true, //parse and render Angular documentation
      showDocularDocs: true, //parse and render Docular documentation
      docAPIOrder : ['doc', 'angular'], //order to load ui resources
      groups: [] //groups of documentation to parse
    }

  });

  // Load the plugin that provides the "docular" tasks.
  grunt.loadNpmTasks('grunt-docular');

  // Default task(s).
  grunt.registerTask('default', ['docular']);

};

a lot of missing resources on the web pages generated after grunt docular.

Using grunt 0.4.2 there are no issues

When you click on a top tier section is starts off blank.

Leads to this:

Then

Is there anyway to get it to display the whole list from first click?

I have a couple directives that require google maps. I would like to do @example for these but can't figure out how to include external js links. would I just create my own home partial and put the script tag there? Can't seem to find any documentation on that.

Hi,

I tried this example and it isn't generated:
http://grunt-docular.com/documentation/docular/docularcreate/firstdoc

Is that documentation is up to date?

The project hasn't had a version bump since 0f16b92, so npm installs of the module are out of date and (among other things) still use the deprecated res.sendfile, which is throwing warnings.

if I configure docular to use docular_partial_home, it's not working.

    docular: {
        docular_partial_home: 'home.html',
    }

Docular is not able to create documentation with this version of nodejs.
I've got bunch of

(node) warning: Recursive process.nextTick detected. This will break in the next version of node. Please use setImmediate for recursive deferral.

and then

RangeError: Maximum call stack size exceeded

I've managed to work around this by replacing all "process.nextTick" -> "setImmediate" in docular source

Done, without errors. ;)

Is there an option to build/copy the contents of

/node_modules/grunt-docular/node_modules/docular/lib/webapp

to say

/docs

I'm a little confused about the baseUrl configuration option. When I set it to "/stuff" here's what I see

• "localhost:port/", as might be expected, is broken, but in a "script didn't load" sort of way;
• "localhost:port/stuff" shows the main documentation page, as I would expect
• the "docular link" on all of the pages goes to localhost:port/, and that is broken as stated before
• other internal links go to localhost:port/documentation, thereby mostly breaking out of the baseUrl.

So I'm wondering if that' s how it's supposed to work, and what purpose it might serve. Is it a work in progress? I would have expected that it would be used to make the entire site run in localhost:port/stuff..., which, given that docular-server (an active server) is currently required, doesn't seem to be all of that appealing anyway....