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>
```
This change allows the example writer to add doc-region annotations to
files that do not allow comments. This is done by creating a clone of the
file and adding `.annotated` to the file name. This new file can contain
inline `// ...` comments that can be used to annotate the doc regions.
Example:
**package.json**
```
{
"name": "angular.io",
"version": "0.0.0",
"main": "index.js",
"repository": "git@github.com:angular/angular.git",
"author": "Angular",
"license": "MIT",
"private": true,
}
````
**package.json.annotated**
```
{
"name": "angular.io",
// #docregion version
"version": "0.0.0",
// #enddocregion
"main": "index.js",
"repository": "git@github.com:angular/angular.git",
"author": "Angular",
"license": "MIT",
"private": true,
}
````
This region can then be referenced in examples just like any other doc region:
```
{@example 'package.json' region="version"}
```
All the docs related files (docs-app, doc-gen, content, etc)
are now to be found inside the `/aio` folder.
The related gulp tasks have been moved from the top level
gulp file to a new one inside the `/aio` folder.
The structure of the `/aio` folder now looks like:
```
/aio/
build/ # gulp tasks
content/ #MARKDOWN FILES for devguides, cheatsheet, etc
devguides/
cheatsheets/
transforms/ #dgeni packages, templates, etc
src/
app/
assets/
content/ #HTML + JSON build artifacts produced by dgeni from /aio/content.
#This dir is .gitignored-ed
e2e/ #protractor tests for the doc viewer app
node_modules/ #dependencies for both the doc viewer builds and the dgeni stuff
#This dir is .gitignored-ed
gulpfile.js #Tasks for generating docs and building & deploying the doc viewer
```
Closes#14361
Georgios Kalpakas
Peter Bacon Darwin
Ward Bell