Variation: Create only one HTML for documentation

[donaldpipowitch]

Hi @petebacondarwin,

most dgeni examples I saw so far show how one doc can be converted to one templated HTML. However I have trouble finding out how to generate just on big HTML - instead of multiple small ones. Given the existing example with app.js and script.js what do I need to change in the config to generate a documentation like this?:

<!-- doc.html -->
<h1>helloWorld</h1>
<p>This function returns a string.</p>

<h2>Returns</h2>
<p>
  { string } - This string has the value 'Hello World'.
</p>

<h1>log</h1>
<p>This function logs a string.</p>

[petebacondarwin]

Hi @donaldpipowitch - thanks for all the issues and PRs you have filed recently. It is very helpful for me to see other use cases and views of people who are working with dgeni.

This is a very good question.

The way I see these things is that each file that will be output is created from a single doc. Each doc is just a JavaScript object with properties, which can be basic strings or complex objects in their own right.

So if you want to render a single file containing everything then you simply create a processor that will create a single doc that contains a property which is a collection the individual docs. Then you returna new docs array containing only this new doc.

You would provide a special template for this doc which will iterate over the collection and render each of the items accordingly.

This processor needs to run before the render-docs pseudo-processor.

I think we should add some kind of "table of contents" doc to this example project to illustrate this.

[donaldpipowitch]

Thank you for the response. I'll try to create such a processor. Don't know when I'll have time for this, though. FYI: I encourage splitting up every material element from the Angular repo into a single repo (see https://github.com/angular/material/issues/161). Maybe this could be a good use case for this: every element creates one help page and a parent repository which refers to all elements include a "frame" for these help pages with navigation, etc. This could look like the current documentation (https://material.angularjs.org/), but the navigation would be generated solely from the elements referenced as dependencies and adding/removing a new element to the documentation would be a simple change in the bower.json or package.json.

[petebacondarwin]

By the way we do this sort of thing already in the AngularJS docs in a couple of the processors: apiDocs.js creates a new module doc for each module in the codebase and in it there is a list of all the components; also we have a component-generate.js processor which does similar but only for specific types of components (e.g. directives, etc).

[donaldpipowitch]

Hi @petebacondarwin, I'm sorry, I can't find either apiDocs.js nor component-generate.js? Could you create a minimal example how to solve this? Thank you.

[petebacondarwin]

https://github.com/angular/dgeni-packages/blob/master/ngdoc/processors/apiDocs.js#L55-L92

and

https://github.com/angular/dgeni-packages/blob/master/ngdoc/processors/generateComponentGroups.js#L37

Although in my latest refactorings these have been moved around a bit. See https://github.com/angular/dgeni-packages/tree/partialIds

[donaldpipowitch]

Ah! I've looked in the Angular repository itself for these, not inside dgeni-packages. Thank you!

[donaldpipowitch]

I know why I was confused. You said

we do this sort of thing already in the AngularJS docs

and I thought you would refer to the AngularJS GitHub repo and not dgeni-packages/ngdocs. The reason for this is that I though ngdocs would be for general projects based on Angular, but it seems that is spe