Live examples

[andy-dorman]

I've just managed to plug in the example tag but haven't investigated a great deal yet. Should I be able to run examples of my own directives yet? If so, where do I point to my compiled app code?

[andy-dorman]

I've looked at the gettext project and attempted to configure my examples to use my application code in a similar way to the Gruntfile in that project. However, it looks like my code isn't being processed correctly despite being referenced in the iFrame, my modules are not being initialised. This is the final piece before I'll be ready to use this in our project so any help would be greatly appreciated. I'm not totally sure how the dependencyPath property in the deployments configuration works for example.

[wingedfox]

Hi Andy,

Thank you for your comment and for your tries to make dgeni-alive working for you.

Comments to the referenced definition is in the code

    require("dgeni-alive/tasks/dgeni-alive").docgen.Package([
        "dgeni-alive/src/packages/jsdoc-ext",
        "dgeni-alive/src/packages/ngdoc-ext",
        "dgeni-alive/src/packages/links-ext",
        "dgeni-alive/src/packages/examples-ext"]) // examples-ext is required, it copies referenced files to the docs
        .config(function (generateExamplesProcessor, generateProtractorTestsProcessor) {
        var cdnUrl = "//ajax.googleapis.com/ajax/libs/angularjs/1.5.0/";
        var deployments = {
            name: "default", // default is referenced below as 'deploymentTarget' name
            examples: {
                commonFiles: {
                    scripts: [
                        cdnUrl + "angular.min.js",
                        "dist/angular-gettext.js" // this file will be copied to the docs by examples-ext package
                    ]
                },
                dependencyPath: cdnUrl
            },
            scripts: [
                cdnUrl + "angular.min.js",
                "../dist/angular-gettext.js" // this is the reference to use in examples
            ],
            stylesheets: [
            ]
        };
        generateExamplesProcessor.deployments = [ deployments ];
        generateProtractorTestsProcessor.deployments = [ deployments ];
    })
    .config(function (renderDocsProcessor) {
        renderDocsProcessor.extraData.deploymentTarget = "default"; // use 'default' deployment
    });

Hope this helps, if not please give me a link to your project and I'll find a way to make it working.

[andy-dorman]

ok so my config looks like this

var packages = [
  require('dgeni-alive/src/packages/jsdoc-ext'),
  require('dgeni-alive/src/packages/ngdoc-ext'),
  require('dgeni-alive/src/packages/links-ext'),
  require('dgeni-alive/src/packages/examples-ext')
  // require('dgeni-packages/git')
];
var path = require('path');
var docgen = require('dgeni-alive/src/docgen')();

docgen.Package(packages)
.config(function(log) {
  log.level = 'info';
})
.config(function (generateExamplesProcessor, generateProtractorTestsProcessor) {
  var deployments = {
    name: 'default',
    examples: {
      commonFiles: {
        scripts: [
          'dist/js/vendor.bundle.js',
          'dist/js/app.bundle.js'
        ]
      }
    },
    scripts: [
      '../dist/js/vendor.bundle.js',
      '../dist/js/app.bundle.js'
    ],
    stylesheets: [
    ]
  };
  generateExamplesProcessor.deployments = [ deployments ];
  generateProtractorTestsProcessor.deployments = [ deployments ];
})
.config(function (renderDocsProcessor) {
    renderDocsProcessor.extraData.deploymentTarget = 'default';
})
.config(function(generateWebsite) {
  generateWebsite.locals('productTitle', 'Sequoia Product Console');
});
docgen.src(['client/src/**/*.js', 'ngdocs/**/*.ngdoc'])
.dest('jsdocs/')
.generate().then(function() {
  console.log('I\'m done!');
});

where vendor.bundle.js and app.bundle.js are generated generated by webapack prior to processing the ngdocs. They files are present when I view the docs on a server...

None of my angular modules seem to be being registered and I'm gettng a "Cannot read property 'document' of undefined" error in both my application files...

[andy-dorman]

I'm also get this in my console when I generate the documentation:

info:    running processor: readFilesProcessor
info:    running processor: extractJSDocCommentsProcessor
info:    running processor: parseExamplesProcessor
info:    running processor: parseTagsProcessor
info:    running processor: filterNgDocsProcessor
info:    running processor: extractTagsProcessor
info:    running processor: codeNameProcessor
info:    running processor: exampleDependenciesBuilder
info:    running processor: generateExamplesProcessor
info:    running processor: generateProtractorTestsProcessor
info:    running processor: computeIdsProcessor
warn:    No getAlias(doc) method provided - doc "default/dist/js/vendor.bundle.js" (example-dependency)
warn:    No getAlias(doc) method provided - doc "default/dist/js/app.bundle.js" (example-dependency)
info:    running processor: memberDocsProcessor
info:    running processor: moduleDocsProcessor
info:    running processor: generateErrorsGroupArea
info:    running processor: generateComponentGroupsProcessor
info:    running processor: providerDocsProcessor
info:    running processor: computePathsProcessor
info:    running processor: generateConfigProcessor
info:    running processor: generateNavigationProcessor
info:    running processor: structuredParamProcessor
info:    running processor: generateWebsite
info:    running processor: renderDocsProcessor
info:    running processor: unescapeCommentsProcessor
info:    running processor: inlineTagProcessor
warn:    Invalid link (does not match any doc): "AUTH_EVENTS" - doc "module:console.app.changePassword.controller:ChangePasswordController" (controller)  - from file "client/src/app/change-password/change-password.controller.js" - starting at line 3, ending at line 153
warn:    Invalid link (does not match any doc): "authService" - doc "module:console.app.changePassword.controller:ChangePasswordController" (controller)  - from file "client/src/app/change-password/change-password.controller.js" - starting at line 3, ending at line 153
warn:    Invalid link (does not match any doc): "flashr" - doc "module:console.app.changePassword.controller:ChangePasswordController" (controller)  - from file "client/src/app/change-password/change-password.controller.js" - starting at line 3, ending at line 153
info:    running processor: generateIndexProcessor
info:    running processor: embedImages
error:   Can't read file: Cannot read property 'filePath' of undefined
error:   Can't read file: Cannot read property 'filePath' of undefined
error:   Can't read file: Cannot read property 'filePath' of undefined
error:   Can't read file: Cannot read property 'filePath' of undefined
error:   Can't read file: Cannot read property 'filePath' of undefined
error:   Can't read file: Cannot read property 'filePath' of undefined
error:   Can't read file: Cannot read property 'filePath' of undefined
info:    running processor: writeFilesProcessor
info:    running processor: checkAnchorLinksProcessor
warn:    Dangling Links Found in "partials/api/console.app.changePassword/controller/ChangePasswordController.html":
 - AUTH_EVENTS,
 - authService,
 - flashr
warn:    3 'unmatched links'

The missing links are no big deal - I just haven't documented those yet, but the "Cannot read property 'filePath' of undefined" errors might be an issue?

[andy-dorman]

I actually think it's trying to parse my imported javascript files - if I pass in non-minified js it tries to process it as documentation...

[andy-dorman]

So I'm fairly certain the root of my issue is the "Cannot read property 'document' of undefined" problem - I can create angular modules inline in example code and they run without problems. I suspect that my project code is falling over due to being unable to read "document" and that's why I'm having problems...

[andy-dorman]

It works if I point my script files to an online location, so http://localhost:8000/js/app.bundle.js, in my case.Other the example package tries to decorate my code with:

function(angular) {
  MY_CODE;
}(window.angular)

which is breaking my code, at least in my specific case...

That will do for me for now, but it would be nice to be able to point to a relative location. If I need to point to a different url and set those up as individual deployments though then that wouldn't be a deal breaker.

[andy-dorman]

Ok, so I've solved this as well...

Adding a template.js file in my local ngdocs/templates directory which looks like this:

{$ doc.fileContents $}

my templates directory is added to my config like so:

.config(function(templateFinder, renderDocsProcessor, gitData) {
  templateFinder.templateFolders.unshift(path.resolve(root, 'ngdocs/templates'));
  renderDocsProcessor.extraData.git = gitData;
})

where root is defined as:

var root = __dirname

[scottux]

Thanks @andy-dorman you helped me get to at least a place where the examples work.

[nhorvath]

To anyone who might come across this issue, I've made some improvements and fixes to live examples in my fork and submitted a PR https://github.com/wingedfox/dgeni-alive/pull/29. If that hasn't been merged feel free to use my fork https://github.com/nhorvath/dgeni-alive. I've also updated the readme with step by step instructions for getting live examples working with grunt.