Gulp support

[keirlawson]

Gulp is proving increasingly popular as a task runner, but right now docular is (seemingly) tied to grunt. It would be great to be able to use docular with gulp, typically gulp doesn't use plugins, prefering to use library APIs directly. I'm not sure if docular is already in a good shape for this sort of usage and it's API (as opposed to grunt-docular) just needs documented, or if work would need to be done to decouple docular from grunt?

[fredericrous]

we should make a gulp-docular plugin

in the midtime, I tried a quick and dirty hack similar to the following in my gulpfile:

var docular = require('docular');
var path = require('path');
var glob = require("glob");
var _ = require('lodash');

gulp.task('docs', function() {

  var opt = {
      useHtml5Mode: false, //Use angular's html5 mode? true/false.
      docular_webapp_target: './docs', //The place where the docs will be generated
      showAngularDocs: false,
      showDocularDocs: false,
      examples: {}, //instructions for how to run the sandboxed examples
      groups: [
                 {
                   groupTitle: 'myproject',
                   groupId: 'myproject',
                   groupIcon: 'icon-book',
                   files: ["gettingstarted.doc"]
                   },
                 {
                     groupTitle: 'Website',
                     groupId: 'web',
                     groupIcon: 'book',
                     sections: [
                         {
                             id: "website",
                             title:"IHM",
                             scripts: './view/*.js'
                         }
                     ]
                 },
                 {
                     groupTitle: 'Server API',
                     groupId: 'serverapi',
                     groupIcon: 'beer',
                     sections: [
                         {
                             id: "serverapi",
                             title: "API",
                             scripts: ['./server/actions/*.js', './server/initializers/*.js', './server/tasks/*.js']
                         }
                     ]
                 }
             ],
  }

 //grunt.file.expand replacer
  for (var g in opt.groups) {
    for (var s in opt.groups[g].sections) {
      if (typeof opt.groups[g].sections[s].scripts === 'string') {
        opt.groups[g].sections[s].scripts = glob.sync(opt.groups[g].sections[s].scripts, {})
      } else {
        var scriptArr = [];
        for (var ss in opt.groups[g].sections[s].scripts) {
          scriptArr.push(glob.sync(opt.groups[g].sections[s].scripts[ss], {}))
        }
        opt.groups[g].sections[s].scripts = _.flatten(scriptArr)
      }
    }
  }

  docular.genDocs(opt);
    return true;
    });

when I do gulp docs, it outputs:

[10:23:20] Starting 'docs'...
[10:23:20] Finished 'docs' after 24 ms
Loading individual files for gid: Base
Loading individual files for gid: myproject
Loading individual files for gid: website
Loading individual files for gid: serverapi
Parsing files for gid:  Base
Parsing files for gid:  myproject
Parsing files for gid:  website
Parsing files for gid:  serverapi
Backfilling file data for gid:  Base
Backfilling file data for gid:  myproject
Backfilling file data for gid:  website
Backfilling file data for gid:  serverapi
Creating docs from for gid:  Base
Creating docs from for gid:  tennis-paris
Creating docs from for gid:  website
Creating docs from for gid:  serverapi
Dependencies saved

I then go to my output dir and start a python simple server:

cd docs
python -m SimpleHTTPServer 8001

the website has the groups myproject, Website and Server API. but they are empty :/ I didn't add correct comments with right syntax for the JS files so it may be the cause but my gettingstarted.doc should appear...I guess!?

[fredericrous]

I think there's a problem with latest version of docular. For the project I work on I finally decided to go with another documentation generator. I'll be happy to switch back to docular for another project when there will be a more stable release out

[trajano]

@Zougi which document generator did you use? So far I'm using esdoc, but it has limitation in that it does not support multiple source folders.

[fredericrous]

@trajano At the time I went with doxx and gulp-doxx. It's not top quality compared to docular but it does the job. For my latest project I needed more than just generated documentation. So I used instead mkdocs + documentationjs. I have a folder wiki with a bunch of markdown files in it and a gulp task that copies readme.md into that folder, generates jsdoc to markdown format with documentationjs and launch a server with mkdocs serve.

[trajano]

Is this the new name for doxx? https://github.com/mr-doc/mr-doc. Looks nice, though I don't see the angular support still :(

[fredericrous]

Yes you're right doxx is now mr-doc

[stephenliberty]

Since this isn't directly related to docular, closing.