ngdoc -- heavy use of nunjucks->partials good?

[laurelnaiad]

At present, docs for Angular code are largely rendered as HTML partials into the docs app.

Thinking out loud here... I wonder if the "balance of power" here (as in, mostly using nunjucks as an HTML generator) is ideal?

Hypothetically, if much more of the documentation information wound up in JSON files, the role of rendering them to HTML could be shifted to Angular directives.

I come to this thought from the perspective of looking at the current Angular docs and starting to think about how in my project I also need to have a single-page rendering (not as in "multipage SPA", but really as in one giant page).

I start to think, well, that one option is to make a completely different set of renderers that would do this. And that may very well be what I should/will end up doing.

However, it strikes me that there's a lot of room in between the current Angular.js docs app and generating a giant HTML page, and that one thing that could -- at least in theory -- be common is that the information gathered in the earlier steps of the dgeni processing could be rendered to JSON files. Such files could be consumed by any Angular app that had some basic ability to present a structured view of the information that is consistent with the overall "schema" that is implied by the (implied) ngdoc specification. If a base Angular app has a set of components that "comprehend" such files, template-based directives could be used to pretty much completely push "up" the question of what the docs app looks like.

In other words, if there was an angular module that knew very well how to consume JSON files that represent ngdocs, that module could be the basis for any arbitrary Angular application to leverage a set of directives to render and otherwise present the information.

I'm not sure if the way I'm expressing this is all that clear, so if this sounds like total nonsense, I can try again, but the short version of an idea I have is:

• dgeni creates JSON files for consumption by (theoretically any) docs presentation app
• a angular module is developed that knows all about the format of said JSON files and has some facilities for getting them in and out of memory and navigating their object model, etc.
• various directives are developed which provide different ways to render the info to browsers

I can see a variety of ways in which this thinking could be countered with issues that it would present, but from the perspective of putting the hands of the docs presentation into angular developers, it seems like it might be one option.

Is the system best as "dgeni with a little angular sprinkled on top"? Or "angular with info parsed by dgeni"? I guess I don't know how you're envisioning it, other than what I see in the present app, which I imagine is somewhat based on earlier incarnations of the angular docs (though I don't know anything about the internals pre-dgeni).

(Just before I am posting this, I took a glance at the Protractor docs for another data point, and it looks like they're pretty much doing what I was trying to describe?)

[petebacondarwin]

Hi @stu-salsbury

Thanks for this post! It is really great to see another perspective of using dgeni. I always envisaged dgeni being completely customisable and so it can certainly support the ideas you present here.

As you say at the bottom the protractor project already uses dgeni to generate its docs in a significantly different manner. Also, I believe, Ionic are using dgeni to create YAML files that are consumed by Jekyll to create the actual web pages.

Are you suggesting that we should change the dgeni packages that generate the core angular.js project documentation to follow this pattern or are you suggesting that this be for documenting angular apps in general?

In my mind I was conceiving of a generic "documenation" web application, to which we could upload multiple projects (or just versions of a single project) with enough metadata to allow the app to generate appropriate navigation. This shell application would be completely separate from dgeni and would specify an unambiguous definition of "documents" to be displayed.

So dgeni is just a document generation tool. It can be configured to produce just about any output you like from just about any input - hey you could even get your source by querying an SQL database if you wanted, or even write the generated documents into a CouchDB store. I guess what I would like to see is the community converging around a set of dgeni "Packages" that are useful to most situations.

I am trying to move the dgeni-packages Packages more toward more generic helpful processors that can be configured per project and don't force the developer to generate any one particular type of app.