vertafore / grunt-docular Goto Github PK
View Code? Open in Web Editor NEWGrunt Plugin for Docular
License: Other
Grunt Plugin for Docular
License: Other
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:
First off, great work putting together what you've done so far.
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 docs
sections 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
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
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....
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.