External Examples

[wolf-daniel]

We found it too cumbersome to write the actual example code/files inline in the documentation markdown.

We thought that being able to have the examples in external files on the filesystem, could be better due to several reasons:

1. Using external files, one could test these examples independently from the ngdocs mechanism. They would be little, actual, runnable web applications.
2. Much easier to write code and markup in real files.
3. Much easier to read the source files later, when the documentation blocks are not massive.
4. Easier to maintain.

The path we took is defining a new annotation, called '@external-example' which is in fact parsed by the grunt-ngdocs plugin.
The hint given to this annotation, i.e. '@external-example:my.example' will look for a directory named 'my/example/' under the base examples directory in the project (by default, a directory named 'examples' under the root dir). All of the files in this example directory will become blocks in the markdown.

Moreover, if the index.html of the example is in fact a full-blown HTML (with and other resources) - the '@external-example' would know to take only the section, since the HTML in the embedded documentation would be generated automatically later.

The base examples directory can be configured in the grunt-ngdocs plugin, the following way:

ngdocs: {
options: {
examplesDir: "my-custom-examples-dir"
}
}

I hope this is clear and useful to others.
Thanks in any case,
Daniel