1616cae5cf
This processor will eventually replace the `{@example}` inline tags
because it provides a cleaner approach that also supports tabbed examples
straight out of the box.
The idea is that authors will simply add a `path` and (optionally) a `region`
attribute to `<code-example>` or `<code-pane>` elements in their docs.
This indicates to dgeni that the relevant example needs to be injected
into the content of this element.
For example, assume that there is an example file `toh-pt1/index.hml` with
a region called `title`, which looks like:
```
<h1>Tour of Heroes</h1>
```
Then the document author could get this to appear in the docs as a
standalone example:
```
<code-example path="toh-pt1" region="title"></code-example>
```
Or as part of a tabbed group:
```
<code-tabs>
<code-pane path="toh-pt1" region="title"></code-pane>
</code-tabs>
```
If no `path` attribute is provided then the element is ignored, which
enables authors to provide inline code instead:
```
<code-example>
Some <html> escaped code
</code-example>
```
Also all attributes other than `path` and `region` are ignored and passed
through to the final rendered output allowing the author to provide
styling hints:
```
<code-example path="toh-pt1" region="title" linenums"15" class="important">
</code-example>
```
Documentation Generation
The dgeni tool is used to generate the documentation from the source files held in this repository.
The documentation generation is configured by a dgeni package defined in docs/angular.io-package/index.js.
This package, in turn requires a number of other packages, some are defined locally in the docs folder,
such as docs/cheatsheet-package and docs/content-package, etc. And some are brought in from the
dgeni-packages node modules, such as jsdoc and nunjucks.
Generating the docs
To generate the documentation simply run gulp docs from the command line.
Testing the dgeni packages
The local packages have unit tests that you can execute by running gulp docs-test from the command line.
What does it generate?
The output from dgeni is written to files in the dist/docs folder.
Notably this includes a partial HTML file for each "page" of the documentation, such as API pages and guides. It also includes JavaScript files that contain metadata about the documentation such as navigation data and keywords for building a search index.
Viewing the docs
You can view the dummy demo app using a simple HTTP server hosting dist/docs/index.html