Can't generate an api index page

[andy-dorman]

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...

[andy-dorman]

Ok, so I got that figured out. For anyone else who's interested I created a file in my project:

ngdocs/api/index.ngdoc

containing this markup:

@ngdoc overview
@name index
@area api
@description My project

and added the ngdocs location to my docgen src:

docgen.src(['client/src/**/*.js', 'client/ngdocs/**/*.ngdoc'])

It does seem to only work if the @name attribute is "index" though - is it possible to modify this so I can use my project title as the name? Also, I'd like to be able to name my package to something other than "API" which is what I'm attempting with this line:

docgen.Package(new Package('Product Console', packages))

I suspect it's something to do with line 22 of docgen.js

/**
 * Applies default package configuration, might be overridden later
 */

How do you override package configuration later?

BTW, this is a very neat project - much better than copying the documentation folder from angularjs which is what I have been doing until now...

[andy-dorman]

Ok, figure that out too!!

Again, for anyone else I managed it by adding these lines to my document generation script:

.config(function(generateWebsite) {
  generateWebsite.locals('productTitle', 'My Project title');
});

I'd appreciate it it if you could let me know if this is correct wingedfox? I also saw this line in docgen.js

generateConfigProcessor.title(title);

but that doesn't seem to be necessary to update the site header.

[wingedfox]

Hi,

Thanks for taking an effort to make things working for you.

I'll check the code and get back to you with the answer, probably this is the obsolete code.

Also, please add a PR with the docs additions.

[Pablodotnet]

We are waiting you come back with the answer...

[wingedfox]

@andy-dorman, index template requires @name index to identify new page as an area root page and display it by default.

To set website title you use correct method, now also you can override template and define title right there.

If I understand you right, 'API' in the header is not the package name, but the area name. There might be 'Guide', 'Error' and other areas as well.