wingedfox / dgeni-alive Goto Github PK

View Code? Open in Web Editor NEW

26.0 26.0 14.0 2.22 MB

Live docs on top of dgeni documentation generator

License: MIT License

HTML 21.10% JavaScript 67.34% CSS 11.57%

dgeni-alive's People

Contributors

Stargazers

Watchers

Forkers

vantanev rose-m northmccormick aprocom wrporter gbbr deemstone andy-dorman pikselpalette nicbell rewathkafley nhorvath appleskiller ljones901

dgeni-alive's Issues

Mismatched angular dependencies 1.6.x

Similar to Issue #17

Pull request : https://github.com/wingedfox/dgeni-alive/pull/20/files may solve this problem.

Running the generated docs is throwing below error
Uncaught Error: [$injector:unpr] Unknown provider: $$MapProvider in ngAnimate module
Looks like ngAnimate is expecting angular 1.6.x but installed version is 1.5.x.

Since ngAnimate is getting installed via ngMaterialize, is there something wrong in bower dependency of ngMaterialize.

Therefore please add "angular-animate": "1.5.x" explicitly in bower.json to avoid any version mismatch.

node_modules > dgeni-alive > src > packages > website > templates > website > bower.json

Error message saying no module was found

I've noticed I need to mark module definitions as belonging to themselves, i.e.

@ngdoc module
@name MyModule
@module MyModule

or I will get error messages saying No MyModule module found, related components:

Looking at Angular's own documentation, for instance for ngResource, they don't do this. Since looking at Angular's stuff is one of the primary ways of picking up the somewhat sparsely documented ngdoc syntax, this can be really confusing for new users (such as me :) )

I humbly suggest either mentioning that this is necessary in the documentation for dgeni-alive, or fixing it so it can live without the @module MyModule when @ngdoc shows a module is being defined. If it helps any, the offending line seems to be in processors/mappers/api.js

Comma missing in the doc

It's not a big deal, but a comma is missing in the Gruntfile at the end of :

packages: [
    'dgeni-packages/jsdoc',            // either names
    require('dgeni-packages/examples') // or packages
]

External links using @link do not work

Markdown links, e.g.:

[ResponsiveBootstrapToolkit](http://github.com/maciej-gurban/responsive-bootstrap-toolkit)

work properly. However, JSDoc-style links, e.g.:

{@link http://github.com/maciej-gurban/responsive-bootstrap-toolkit ResponsiveBootstrapToolkit}

result in almost correct, yet malformed <a> tags.

Mismatched angular dependencies

Hi,

Our doc build has recently started failing - I suspect since angular 1.6 dropped.

We're getting this:

Uncaught Error: [$injector:unpr] Unknown provider: $$isDocumentHiddenProvider <- $$isDocumentHidden <- $$animateQueue <- $animate <- $compile <- $$animateQueue

It's caused because the angular depdency is set to 1.5.x but somewhere else there is an angaulr-animate dependency that is now at 1.6 - you can see this by looking in the generated bower_components directory. This can be fixed by specifiying a matching versionsin:

packages > website > templates > website > bower.json

angular: 1.5.9
angular-animate: 1.5.9

seems to work, it doesn't look ready for 1.6 yet - I know our application certainly isn't...

So two questions really:

Do you want me to submit a pull request to fix it?
or
Is there a way of overriding the bower.json file used in the generateWebsiteProcessor?

Cannot read property 'includes' of undefined

Using v0.4.1 with grunt I get this error when I run grund dgeni-alive:

Running "dgeni-alive:api" (dgeni-alive) task
Warning: Cannot read property 'includes' of undefined Use --force to continue.

I tried on the angular-route-segment example.

readFilesProcessor module not found

I've been looking for an angular documentation generator for a while now and hadn't decided on one. Then I saw the demos, something not given by many documentation generators so props for that, and decided to give it a try.

followed all given steps, which are not clear at all, and executed the task: got errors saying
-Invalid property in "readFilesProcessor" (in "base" package)
-sourceFiles=[Source files can't be blank]
-error processing docs: processor=readFilesProcessor, package=base, sourceFiles=[Source files can't be blank]

I assume this is a simple error. Given that after reading thru several files I found no readFilesProcessor module being exported and that the module is never really imported into the docgen.js file. I assume it should be solved by including this module, which might have been left out by mistake, and requiring it inside the docgen.js file.

This looks to be one of the best tools for angular documentation generation, if it was documented..

Incompatibilities with dgeni-packages 0.13.x

With version 0.13.x of dgeni-packages, there is a bug in checkAnchorLinks.js on line 13 where existence of doc.outputPath is not checked. I recommend upgrading to 0.16.0.

Also, there is a bug when using the examples-ext package, where path is not defined. The following line should be added at the top of the file.

var path = require('path');

deployments=[Deployments can't be blank]

I'm trying to get the Grunt Task running but I pathetically fail

Running "dgeni-alive:all" (dgeni-alive) task
error:   Invalid property in "generateExamplesProcessor" (in "examples" package)
error:    deployments=[Deployments can't be blank]
error:   Invalid property in "generateProtractorTestsProcessor" (in "examples" package)
error:    deployments=[Deployments can't be blank]
error:   Error processing docs:  processor=generateExamplesProcessor, package=examples, deployments=[Deployments can't be blank], processor=generateProtractorTestsProcessor, package=examples, deployments=[Deployments can't be blank]

My Grunt config is rather simple

options: {
    basePath: '',
    port: 10000,
    openBrowser: true
},
all: {
    title: 'My Docs',
    version: '<%= pkg.version %>',
    expand: false,
    deployments: [
        {name: 'local'}
    ],
    dest: '/docs/js/',
    src: ['src/app/**/*.js', 'vendor/angular/angular.js']
}

https://github.com/angular/dgeni-packages#deployment-configuration shows how to set this property but I have no idea how to set this via my Grunt config.

How can I adjust my Grunt config to get rid of this error without disabling the 'examples' package (if possible).

Thanks.

Can't generate an api index page

Or any other static .ngdocs. I'm generating my docs using the API with this script:

require('dgeni-packages/examples');
var path = require('path');
var docgen = require('dgeni-alive/src/docgen')();
var Package = require('dgeni').Package;
var packages = [
  require('dgeni-packages/ngdoc'),
  require('dgeni-packages/nunjucks'),
  require('dgeni-packages/examples'),
  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')
];
docgen.Package(new Package('Product Console', packages))
.config(function(log) {
  log.level = 'info';
})
.config(function(generateExamplesProcessor, generateProtractorTestsProcessor) {
  var deployments = [
    { name: 'default' }
  ];
  generateExamplesProcessor.deployments = deployments;
  generateProtractorTestsProcessor.deployments = deployments;
});
docgen.src(['client/src/app/**/*.js'])
.dest('jsdocs/')
.generate().then(function() {
  console.log("I'm done!");
});

and I'm getting this output:

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
info:    running processor: memberDocsProcessor
info:    running processor: moduleDocsProcessor
info:    running processor: generateErrorsGroupArea
info:    running processor: generateComponentGroupsProcessor
info:    running processor: providerDocsProcessor
info:    running processor: collectKnownIssuesProcessor
info:    running processor: computePathsProcessor
info:    running processor: generateConfigProcessor
info:    running processor: generateNavigationProcessor
warn:    No index document found for "api"
Create api/index.ngdoc file in the documents area with template
===================
@ngdoc overview
@name index
@area api
@description Module Overview
info:    running processor: structuredParamProcessor
info:    running processor: generateWebsite
info:    running processor: renderDocsProcessor
info:    running processor: unescapeCommentsProcessor
info:    running processor: inlineTagProcessor
info:    running processor: generateIndexProcessor
info:    running processor: embedImages
info:    running processor: writeFilesProcessor
info:    running processor: checkAnchorLinksProcessor
I'm done!

Looks as though I need to create an api/index.ngdoc file somewhere but I'm not totally clear where? I'm assuming I can create this kind of thing in my project and point dgeni-alive at it?

Like many others I feel I'm more than a little in the dark as to exactly how dgeni wants to work...

Error: Cannot find module './processors/order-nav-items'

Where

https://github.com/wingedfox/dgeni-alive/blob/master/src/packages/navigation/index.js#L12

Why

no such processor in src/packages/navigation/processors

/partials/index.html 404 (Not Found)

I'm trying to setup dgeni-alive to generate the doc for an AngularJS app.

First here is my gruntfile.js :

module.exports = function(grunt) {

    // Project configuration.
    grunt.initConfig({
        "dgeni-alive": {
            options: {
                  serve: {
                      port: '3000',
                      openBrowser: false
                  },
            },
            api: {
                title: 'MyApp',
                version: '0.0.1',
                expand: false,
                dest: 'build/docs/',
                src: [
                'src/**/*.js',
                'docs/**/*.ngdoc'
                ]
            }
        }
    });

    grunt.loadNpmTasks('dgeni-alive');
    grunt.registerTask("default", [ 'dgeni-alive' ]);

};

And I have the following api.ngdoc file in docs/api :

@ngdoc overview
@name index
@area api
@title API Docs
@description
# My API Docs

Welcome to the my API docs page.

When I run the grunt task everything goes well, no error, no warning, nothing and the web server is well launched.

I can reach http://localhost:3000/ and it works, I get the following screen :

I can also make a search with the top right corner input and get the doc, by example, of routeSegmentContains.

But if I try to click one of the link on the left side menu I get the following error in the browser console :

GET http://localhost:3000/partials/index.html 404 (Not Found)

And I can't find why I get this error and if I missed something !?

Live examples

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?

A way to omit the Installation documentation from a module

Currently, there seems to be no way to omit or change the installation documentation for a module.
When using dgeni-alive for a private project documentation, and there are multiple sub-modules, this is just distracting.

Maybe just adding a check similar to this in the installation template would be enough: https://github.com/angular/angular.js/blob/3bcbd63e47b7a7210ca8cf0ad75d14605018c91e/docs/config/templates/api/module.template.html#L9-L11 (or, maybe the check should be:
If @installation is present, use that, otherwise check for @packageName and use the current version, or dispaly nothing

Adding a sortOrder tag to documents

I've added a config call that processes @sortorder markup in my documents:

.config(function(parseTagsProcessor) {
  parseTagsProcessor.tagDefinitions.push(require('./ngdocs/config/tag-defs/sortOrder'));
})

that looks like this:

module.exports = {
  name: 'sortOrder',
  transforms: function(doc, tag, value) {
    return parseInt(value, 10);
  }
};

and that this is allowing me to write markup that looks like this

@ngdoc overview
@name ie
@title Internet Explorer Compatibility
@sortOrder 530
@area guide

and I can see that this is being processed correctly in a subsequent processor:

.processor(require('./ngdocs/processors/orderNavItems'))

that looks like this

var _ = require('lodash');

module.exports = function generatePagesDataProcessor(log) {
  return {
    $runAfter: ['paths-computed'],
    $runBefore: ['rendering-docs'],
    $process: function(docs) {
      // We are only interested in docs that are in an area
      docs = _(docs)
      .sortBy(function(g) {
        return g.sortOrder;
      })
      .value();

    }
  }
};

How can I get this ordering to be respected in the subsequent mapper processors? I'm sure I'm simply misunderstanding the order of things in dgeni...

HELP! Unrecognised node type: LogicalExpression

With this code

/**
 * @ngdoc method
 * @name foo#bar
 * @description
 * Does important bar stuff on foo and will only be present if `readOnly` flag isn't set
**/

foo.bar = !options.readOnly && function() {
    // blabla
}

I get the following output when running the grunt task:

warn:    HELP! Unrecognised node type: LogicalExpression
warn:     type=LogicalExpression, operator=&&, type=UnaryExpression, operator=!, type=MemberExpression, computed=false, type=Identifier, name=options, range=[1438, 1445], line=51, column=15, line=51, column=22, type=Identifier, name=readOnly, range=[1446, 1454], line=51, column=23, line=51, column=31, range=[1438, 1454], line=51, column=15, line=51, column=31, prefix=true, range=[1437, 1454], line=51, column=14, line=51, column=31, type=FunctionExpression, id=null, params=[], type=BlockStatement, body=[], range=[1469, 1494], line=51, column=46, line=53, column=5, trailingComments=[type=Line, value= blabla, range=[1479, 1488], line=52, column=8, line=52, column=17], generator=false, expression=false, range=[1458, 1494], line=51, column=35, line=53, column=5, range=[1437, 1494], line=51, column=14, line=53, column=5

If I replace the assignment with if (!options.readOnly) foo.bar = ..., I instead get

warn:    HELP! Unrecognised node type: IfStatement
warn:     type=IfStatement, type=UnaryExpression, operator=!, type=MemberExpression, computed=false, type=Identifier, name=options, range=[1432, 1439], line=51, column=9, line=51, column=16, type=Identifier, name=readOnly, range=[1440, 1448], line=51, column=17, line=51, column=25, range=[1432, 1448], line=51, column=9, line=51, column=25, prefix=true, range=[1431, 1448], line=51, column=8, line=51, column=25, type=ExpressionStatement, type=AssignmentExpression, operator==, type=MemberExpression, computed=false, type=Identifier, name=foo, range=[1450, 1453], line=51, column=27, line=51, column=30, type=Identifier, name=bar, range=[1454, 1457], line=51, column=31, line=51, column=34, range=[1450, 1457], line=51, column=27, line=51, column=34, type=FunctionExpression, id=null, params=[], type=BlockStatement, body=[], range=[1471, 1496], line=51, column=48, line=53, column=5, trailingComments=[type=Line, value= blabla, range=[1481, 1490], line=52, column=8, line=52, column=17], generator=false, expression=false, range=[1460, 1496], line=51, column=37, line=53, column=5, range=[1450, 1496], line=51, column=27, line=53, column=5, range=[1450, 1497], line=51, column=27, line=53, column=6, alternate=null, range=[1427, 1497], line=51, column=4, line=53, column=6, leadingComments=[type=Block, value=*
     * @ngdoc method
     * @name foo#bar
     * Does important bar stuff on foo and will only be present if `readOnly` flag isn't set.
     , range=[1274, 1421], line=45, column=4, line=49, column=7]

I've been able to trace it to function findCodeName in packages/jsdoc-ext/services/code-name.js.

How do you use this?

dgeni-alive is a documentation generator and there are no... docs?

Why not use dgeni-alive to generate some?

The example

var docgen = require('../scr/docgen')(); // src is spelled wrong.
docgen.package().config(function(log) { // package should be Package
    log.level = 'info';
})
.src(/* what the heck goes here? */);
.dest(/* a directory pathI assume? */);
.generate() // generates the HTML output I suppose.
.then(function(/* any parameters here? */){
  console.log("I'm done!");
});

doesn't really explain anything.

Please, can you document dgeni-alive and how to use it by itself (no grunt).