Peter Bacon Darwin
Igor Minar
parent
48cd503d4a
commit
4c73b52d5c
|
|
@ -18,52 +18,53 @@ See the [README.md](cli-patches/README.md) for more details.
|
|||
|
||||
## examples
|
||||
|
||||
Many of the documentation pages contain snippets of code examples. We extract these snippets from real working example
|
||||
applications, which are stored in subfolders of the `/aio/content/examples` folder. Each example can be built and run
|
||||
independently. Each example also provides e2e specs, which are run as part of our Travis build tasks, to verify that the
|
||||
examples continue to work as expected, as changes are made to the core Angular libraries.
|
||||
Many of the documentation pages contain snippets of code examples. We extract these snippets from real
|
||||
working example applications, which are stored in subfolders of the `/aio/content/examples` folder. Each
|
||||
example can be built and run independently. Each example also provides e2e specs, which are run as part
|
||||
of our Travis build tasks, to verify that the examples continue to work as expected, as changes are made
|
||||
to the core Angular libraries.
|
||||
|
||||
In order to build, run and test these examples independently we need to install dependencies into their sub-folder. Also
|
||||
there are a number of common boilerplate files that are needed to configure each example's project. We maintain these
|
||||
common boilerplate files centrally to reduce the amount of effort if one of them needs to change.
|
||||
In order to build, run and test these examples independently we need to install dependencies into their
|
||||
sub-folder. Also there are a number of common boilerplate files that are needed to configure each
|
||||
example's project. We maintain these common boilerplate files centrally to reduce the amount of effort
|
||||
if one of them needs to change.
|
||||
|
||||
This `examples` tool folder contains two utilities:
|
||||
|
||||
* add-example-boilerplate.js - install the npm dependencies and boilerplate files into each of the examples' subfolders.
|
||||
* example-boilerplate.js - install/remove the npm dependencies and boilerplate files into/from each of the
|
||||
examples' subfolders.
|
||||
* run-example-e2e.js - run the e2e tests for one or more examples
|
||||
|
||||
See the [README.md](examples/README.md) for more details.
|
||||
|
||||
## example-zipper
|
||||
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project
|
||||
packaged as a zip file. These zip files are generated by the utility in this folder.
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained
|
||||
runnable project packaged as a zip file. These zip files are generated by the utility in this folder.
|
||||
|
||||
See the [README.md](example-zipper/README.md) for more details.
|
||||
|
||||
## plunker-builder
|
||||
|
||||
In the AIO application, we can embed a running version of the example as a [Plunker](http://plnkr.co/). We can also provide a
|
||||
link to create a runnable version of the example in the [Plunker](http://plnkr.co/edit) editor.
|
||||
|
||||
This folder contains three utilities:
|
||||
|
||||
* regularPlunker.js - generates an HTML file for each example that will post to Plunker to create a new editable project, when rendered.
|
||||
* embeddedPlunker.js - generates an HTML file for each example that can be used in an iframe to render an embedded Plunker project.
|
||||
* generatePlunkers.js - executes each of the `regularPlunker.js` and `embeddedPlunker.js` utilities to generate all the example plunker files.
|
||||
In the AIO application, we can embed a running version of the example as a [Plunker](http://plnkr.co/).
|
||||
We can also provide a link to create a runnable version of the example in the [Plunker](http://plnkr.co/edit)
|
||||
editor.
|
||||
|
||||
This folder contains three utilities: `regularPlunker.js`, `embeddedPlunker.js`, `generatePlunkers.js`.
|
||||
See the [README.md](plunker-builder/README.md) for more details.
|
||||
|
||||
## transforms
|
||||
|
||||
All the content that is rendered by the AIO application, and some of its configuration files, are generated from source files
|
||||
by [Dgeni](https://github.com/angular/dgeni). Dgeni is a general purpose documentation generation tool.
|
||||
All the content that is rendered by the AIO application, and some of its configuration files, are
|
||||
generated from source files by [Dgeni](https://github.com/angular/dgeni). Dgeni is a general purpose
|
||||
documentation generation tool.
|
||||
|
||||
Markdown files in `/aio/content`, code comments in the core Angular source files and example files are processed and transformed
|
||||
into files that are consumed by the AIO application.
|
||||
Markdown files in `/aio/content`, code comments in the core Angular source files and example files are
|
||||
processed and transformed into files that are consumed by the AIO application.
|
||||
|
||||
Dgeni is configured by "packages", which contain services and processors. Some of these packages are installed as `node_modules`
|
||||
from the [dgeni-packages](https://github.com/angular/dgeni-packages) and some are specific to the AIO project.
|
||||
Dgeni is configured by "packages", which contain services and processors. Some of these packages are
|
||||
installed as `node_modules` from the [dgeni-packages](https://github.com/angular/dgeni-packages) and
|
||||
some are specific to the AIO project.
|
||||
|
||||
The project specific packages are stored in the `aio/tools/transforms` folder. See the [README.md](transforms/README.md)
|
||||
for more details.
|
||||
The project specific packages are stored in the `aio/tools/transforms` folder. See the
|
||||
[README.md](transforms/README.md) for more details.
|
||||
|
|
|
|||
|
|
@ -4,3 +4,4 @@ The AIO application is built using the Angular CLI tool. We are often trialling
|
|||
we apply to the library after it is installed. This folder contains git patch files that contain these new features
|
||||
and a utility to apply those patches to the CLI library.
|
||||
|
||||
**Currently, we have no patches to run.**
|
||||
|
|
@ -1,10 +1,13 @@
|
|||
# Overview
|
||||
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project packaged as a zip file. These zip files are generated by the utility in this folder.
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained
|
||||
runnable project packaged as a zip file. These zip files are generated by the utility in this folder.
|
||||
|
||||
## Example zipper
|
||||
|
||||
The `exampleZipper.js` tool is very similar to the Plunker's `builder.js`. The latter creates an HTML file with all the examples' files and the former creates a zip file instead. They both use the `plnkr.json` file to flag an example as something to plunker or zip. For example:
|
||||
The `exampleZipper.js` tool is very similar to the Plunker's `builder.js`. The latter creates an HTML file
|
||||
with all the examples' files and the former creates a zip file instead. They both use the `plnkr.json` file
|
||||
to flag an example as something to plunker or zip. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -23,11 +26,14 @@ The zipper will use this information for creating new zips.
|
|||
|
||||
## Three kinds of examples
|
||||
|
||||
The majority of examples in AIO use `System.js` but there are also `CLI` and `Webpack` projects. This tool is able to differentiate between them.
|
||||
The majority of examples in AIO use `System.js` but there are also `CLI` and `Webpack` projects. This
|
||||
tool is able to differentiate between them.
|
||||
|
||||
The boilerplate uses a `package.json` that contains packages and scripts to run any kind of example. Using that `package.json` in the zips would confuse the users.
|
||||
The boilerplate uses a `package.json` that contains packages and scripts to run any kind of example.
|
||||
Using that `package.json` in the zips would confuse the users.
|
||||
|
||||
Thanks to the `package.json` customizer, we can create a new `package.json` on the fly that would only contain the packages and scripts needed to run that example.
|
||||
Thanks to the `package.json` customizer, we can create a new `package.json` on the fly that would
|
||||
only contain the packages and scripts needed to run that example.
|
||||
|
||||
The `exampleZipper.js` won't include any `System.js` related files for `CLI` or `Webpack` projects.
|
||||
|
||||
|
|
@ -40,15 +46,18 @@ Here you find a:
|
|||
* **base.json** - All the common scripts and packages
|
||||
* **cli.json** - Extra scripts and packages for the CLI
|
||||
* **webpack.json** - Extra scripts and packages for Webpack
|
||||
* **systemjs.json** - All the System.js related packages but it also contains the remainder scripts that are not in the other files.
|
||||
* **systemjs.json** - All the System.js related packages but it also contains the remainder scripts
|
||||
that are not in the other files.
|
||||
|
||||
The tool will also give some standard names to the scripts.
|
||||
The tool will also give some standard names to the scripts.
|
||||
|
||||
## The zipper.json
|
||||
|
||||
As mentioned, the tool uses the `plnkr.json` as a flag and also a configuration file for the zipper. The problem is that not all examples have a plunker but they could offer a zip instead.
|
||||
As mentioned, the tool uses the `plnkr.json` as a flag and also a configuration file for the zipper.
|
||||
The problem is that not all examples have a plunker but they could offer a zip instead.
|
||||
|
||||
In those cases, you can create a `zipper.json` file with the same syntax. It will be ignored by the plunker tool.
|
||||
In those cases, you can create a `zipper.json` file with the same syntax. It will be ignored by the
|
||||
plunker tool.
|
||||
|
||||
## Choosing the zip "type"
|
||||
|
||||
|
|
@ -62,7 +71,8 @@ In both `plnkr.json` and `zipper.json` you can use two extra properties for the
|
|||
}
|
||||
```
|
||||
|
||||
This would generate a zip for a webpack application and it will also remove everything related with SystemJS.
|
||||
This would generate a zip for a webpack application and it will also remove everything related with
|
||||
SystemJS.
|
||||
|
||||
## Executing the zip generation
|
||||
|
||||
|
|
@ -70,4 +80,5 @@ This would generate a zip for a webpack application and it will also remove ever
|
|||
|
||||
Where? At `src/generated/zips/`.
|
||||
|
||||
Then the `<live-example>` embedded component will look at this folder to get the zip it needs for the example.
|
||||
Then the `<live-example>` embedded component will look at this folder to get the zip it needs for
|
||||
the example.
|
||||
|
|
|
|||
|
|
@ -1,34 +1,54 @@
|
|||
# Overview
|
||||
|
||||
Many of the documentation pages contain snippets of code examples. We extract these snippets from real working example applications, which are stored in subfolders of the `/aio/content/examples` folder. Each example can be built and run independently. Each example also provides e2e specs, which are run as part of our Travis build tasks, to verify that the examples continue to work as expected, as changes are made to the core Angular libraries.
|
||||
Many of the documentation pages contain snippets of code examples. We extract these snippets from
|
||||
real working example applications, which are stored in subfolders of the `/aio/content/examples`
|
||||
folder. Each example can be built and run independently. Each example also provides e2e specs, which
|
||||
are run as part of our Travis build tasks, to verify that the examples continue to work as expected,
|
||||
as changes are made to the core Angular libraries.
|
||||
|
||||
In order to build, run and test these examples independently we need to install dependencies into their sub-folder. Also there are a number of common boilerplate files that are needed to configure each example's project. We maintain these common boilerplate files centrally to reduce the amount of effort if one of them needs to change.
|
||||
In order to build, run and test these examples independently we need to install dependencies into
|
||||
their sub-folder. Also there are a number of common boilerplate files that are needed to configure
|
||||
each example's project. We maintain these common boilerplate files centrally to reduce the amount
|
||||
of effort if one of them needs to change.
|
||||
|
||||
## Boilerplate overview
|
||||
|
||||
As mentioned, many of the documentation pages contain snippets extracted from real example applications. To achieve that, all those applications needs to contain a basic boilerplate. E.g. a `node_modules` folder, `package.json` with scripts, `system.js` configuration, etc.
|
||||
As mentioned, many of the documentation pages contain snippets extracted from real example applications.
|
||||
To achieve that, all those applications needs to contain a basic boilerplate. E.g. a `node_modules`
|
||||
folder, `package.json` with scripts, `system.js` configuration, etc.
|
||||
|
||||
No one wants to maintain the boilerplate on each example, so the goal of this tool is to provide a generic boilerplate that works in all the examples.
|
||||
No one wants to maintain the boilerplate on each example, so the goal of this tool is to provide a
|
||||
generic boilerplate that works in all the examples.
|
||||
|
||||
### Boilerplate files
|
||||
|
||||
Inside `/aio/tools/examples/shared/boilerplate` you will see all the common boilerplate you can find in any Angular application using System.js. This is the boilerplate that will be carried to each example.
|
||||
Inside `/aio/tools/examples/shared/boilerplate` you will see all the common boilerplate you can find
|
||||
in any Angular application using System.js. This is the boilerplate that will be carried to each example.
|
||||
|
||||
Among these files, there are a few special ones:
|
||||
|
||||
* **src/systemjs.config.js** - This is the configuration of System.js used to run the example locally.
|
||||
* **src/systemjs.config.web.js** - This configuration replaces the previous one on Plunkers.
|
||||
* **/src/systemjs.config.web.build.js** - Same as the previous one but for using angular's `-builds` versions.
|
||||
* **src/systemjs.config.web.build.js** - Same as the previous one but for using angular's `-builds`
|
||||
versions.
|
||||
* **src/systemjs-angular-loader.js** - It is a System.js plugin that removes the need of `moduleId`.
|
||||
* **package.json** - This package.json only contains scripts, no dependencies. It contains the different tasks needed to run any example. Doesn't matter if CLI, System.js or Webpack.
|
||||
* **plnkr.json** - This file is used by the Plunker tool to generate a plunker for an example. This concrete file is just a placeholder. Authors needs to tweak it for each guide. More at the [plunker docs](../plunker-builder/README.md).
|
||||
* **example-config.json** - This file serves as a flag to indicate that the current folder is an example. This concrete file is just a placeholder. More on this later in this readme.
|
||||
* **package.json** - This package.json only contains scripts, no dependencies. It contains the
|
||||
different tasks needed to run any example. Doesn't matter if CLI, System.js or Webpack.
|
||||
* **plnkr.json** - This file is used by the Plunker tool to generate a plunker for an example. This
|
||||
concrete file is just a placeholder. Authors needs to tweak it for each guide. More at the
|
||||
[plunker docs](../plunker-builder/README.md).
|
||||
* **example-config.json** - This file serves as a flag to indicate that the current folder is an
|
||||
example. This concrete file is just a placeholder. More on this later in this readme.
|
||||
|
||||
### The example-config.json
|
||||
|
||||
So what is this **example-config.json** again? If an author wants to create a new example, say `/aio/content/examples/awesome-example`. The author needs to create an empty `example-config.json` in that folder. That serves as a flag so this tool will say "Hey, that is an example, let's copy all the boilerplate there".
|
||||
So what is this **example-config.json** again? If an author wants to create a new example, say
|
||||
`/aio/content/examples/awesome-example`. The author needs to create an empty `example-config.json`
|
||||
in that folder. That serves as a flag so this tool will say "Hey, that is an example, let's copy
|
||||
all the boilerplate there".
|
||||
|
||||
So when the tool runs, it finds **all** the folders with an `example-config.json` file, and puts a copy of the boilerplate in those folders.
|
||||
So when the tool runs, it finds **all** the folders with an `example-config.json` file, and puts
|
||||
a copy of the boilerplate in those folders.
|
||||
|
||||
Normally the file is empty, but we can add information in it, for example:
|
||||
|
||||
|
|
@ -39,33 +59,50 @@ Normally the file is empty, but we can add information in it, for example:
|
|||
}
|
||||
```
|
||||
|
||||
In this case, this would indicate that this is a CLI example. Won't make any difference on the boilerplate, but will be useful for e2e tests (more on this later). Also works as a hint for the example to know how is executed.
|
||||
In this case, this would indicate that this is a CLI example. Won't make any difference on the
|
||||
boilerplate, but will be useful for e2e tests (more on this later). Also works as a hint for
|
||||
the example to know how is executed.
|
||||
|
||||
|
||||
### A node_modules to share
|
||||
|
||||
With all the boilerplate files in place, the only missing piece are the installed packages. For that we have a `/aio/tools/examples/shared/package.json` which contains **all** the packages needed to run all the examples.
|
||||
With all the boilerplate files in place, the only missing piece are the installed packages. For
|
||||
that we have a `/aio/tools/examples/shared/package.json` which contains **all** the packages
|
||||
needed to run all the examples.
|
||||
|
||||
After installing these dependencies, a `node_modules` will be created at `/aio/tools/examples/shared/node_modules`. This folder will be **symlinked** into each example. So it is not a copy like the other boilerplate files. This solution works in all OSes. Windows may require admin rights.
|
||||
After installing these dependencies, a `node_modules` will be created at
|
||||
`/aio/tools/examples/shared/node_modules`. This folder will be **symlinked** into each example.
|
||||
So it is not a copy like the other boilerplate files. This solution works in all OSes. Windows
|
||||
may require admin rights.
|
||||
|
||||
### End to end tests
|
||||
|
||||
Each example contains an `e2e-spec.ts` file. We can find all the related configuration files for e2e in the `/aio/tools/examples/shared` folder.
|
||||
Each example contains an `e2e-spec.ts` file. We can find all the related configuration files for
|
||||
e2e in the `/aio/tools/examples/shared` folder.
|
||||
|
||||
This tool expects all the examples to be build with `npm run build`. If an example is not built with that script, the author would need to specify the new build command in the `example-config.json` as shown earlier.
|
||||
This tool expects all the examples to be build with `npm run build`. If an example is not built
|
||||
with that script, the author would need to specify the new build command in the `example-config.json`
|
||||
as shown earlier.
|
||||
|
||||
### add-example-boilerplate.js
|
||||
|
||||
This script installs all the dependencies that are shared among all the examples, creates the `node_modules` symlinks and copy all the boilerplate files where needed. It won't do anything about plunkers nor e2e tests.
|
||||
This script installs all the dependencies that are shared among all the examples, creates the
|
||||
`node_modules` symlinks and copy all the boilerplate files where needed. It won't do anything
|
||||
about plunkers nor e2e tests.
|
||||
|
||||
It also contains a function to remove all the boilerplate. It uses a `git clean -xdf` to do the job. It will remove all files that don't exist in the git repository, **including any new file that you are working on that hasn't been stage yet.** So be sure to save your work before removing the boilerplate.
|
||||
It also contains a function to remove all the boilerplate. It uses a `git clean -xdf` to do
|
||||
the job. It will remove all files that don't exist in the git repository, **including any
|
||||
new file that you are working on that hasn't been stage yet.** So be sure to save your work
|
||||
before removing the boilerplate.
|
||||
|
||||
### run-example-e2e.js
|
||||
|
||||
This script will find all the `e2e-spec.ts` files and run them.
|
||||
|
||||
To not run all tests, you can use the `--filter=name` flag to run the example's e2e that contains that name.
|
||||
To not run all tests, you can use the `--filter=name` flag to run the example's e2e that contains
|
||||
that name.
|
||||
|
||||
It also has an optional `--setup` flag to run the `add-example-boilerplate.js` script and install the latest `webdriver`.
|
||||
It also has an optional `--setup` flag to run the `add-example-boilerplate.js` script and install
|
||||
the latest `webdriver`.
|
||||
|
||||
It will create a `/aio/protractor-results-txt` file when it finishes running tests.
|
||||
|
|
|
|||
|
|
@ -1,24 +1,41 @@
|
|||
# Overview
|
||||
|
||||
[Plunker](http://plnkr.co) is an online tool for creating, collaborating and sharing ideas. In AIO we use it to share one or more runnable versions of our examples.
|
||||
[Plunker](http://plnkr.co) is an online tool for creating, collaborating and sharing ideas. In AIO
|
||||
we use it to share one or more runnable versions of our examples.
|
||||
|
||||
Plunker comes in two flavours. The [classic UI](http://plnkr.co/edit) and a [embedded UI](http://embed.plnkr.co). The latter can be used both in a new tab or embedded within a guide. The AIO project uses the embedded version in both ways.
|
||||
Plunker comes in two flavours. The [classic UI](http://plnkr.co/edit) and an [embedded UI](http://embed.plnkr.co).
|
||||
The latter can be used both in a new tab or embedded within a guide. The AIO project uses the
|
||||
embedded version in both ways.
|
||||
|
||||
* `regularPlunker.js` - generates an HTML file for each example that will post to Plunker to create
|
||||
a new editable project, when rendered.
|
||||
* `embeddedPlunker.js` - generates an HTML file for each example that can be used in an iframe to
|
||||
render an embedded Plunker project.
|
||||
* `generatePlunkers.js` - executes each of the `regularPlunker.js` and `embeddedPlunker.js` utilities
|
||||
to generate all the example plunker files.
|
||||
|
||||
## Plunker generation
|
||||
|
||||
Both flavours are created within `builder.js`. How is a plunker created? What is the process from a directory with files to a link with a plunker.
|
||||
Both flavours are created within `builder.js`. How is a plunker created? What is the process from a
|
||||
directory with files to a link with a plunker.
|
||||
|
||||
An "executable" plunker is an HTML file with a `<form>` that makes a post to plunker on submit. It contains an `<input>` element for each file we need in the plunker.
|
||||
An "executable" plunker is an HTML file with a `<form>` that makes a post to plunker on submit. It
|
||||
contains an `<input>` element for each file we need in the plunker.
|
||||
|
||||
The form will be submitted on load, so you can either double click the HTML file or open it with an anchor tag to open the plunker.
|
||||
The form will be submitted on load, so you can either double click the HTML file or open it with an
|
||||
anchor tag to open the plunker.
|
||||
|
||||
So the `builder.js` job is to get all the needed files from an example and build this HTML file for you.
|
||||
|
||||
For plunkers, we use a special `systemjs.config` that exists in `/aio/tools/examples/shared/boilerplate/src/systemjs.config.web.js` and we also add the Google's copyright to each file.
|
||||
For plunkers, we use a special `systemjs.config` that exists in
|
||||
`/aio/tools/examples/shared/boilerplate/src/systemjs.config.web.js` and we also add the Google's copyright
|
||||
to each file.
|
||||
|
||||
## Customizing the generation per example basis
|
||||
|
||||
How does this tool know what is an example and what is not? It will look for all folders containing a `plnkr.json` file. If found, all files within the folder and subfolders will be used in the plunker, with a few generic exceptions that you can find at `builder.js`.
|
||||
How does this tool know what is an example and what is not? It will look for all folders containing a
|
||||
`plnkr.json` file. If found, all files within the folder and subfolders will be used in the plunker, with
|
||||
a few generic exceptions that you can find at `builder.js`.
|
||||
|
||||
You can use the `plnkr.json` to customize the plunker generation. For example:
|
||||
|
||||
|
|
@ -35,13 +52,15 @@ You can use the `plnkr.json` to customize the plunker generation. For example:
|
|||
}
|
||||
```
|
||||
|
||||
Here you can specify a description for the plunker, some tags, a basePath and also a files array where you can specify extra files to add or to ignore.
|
||||
Here you can specify a description for the plunker, some tags, a basePath and also a files array where you
|
||||
can specify extra files to add or to ignore.
|
||||
|
||||
## Classic plunkers and embedded ones
|
||||
|
||||
Luckily, both kind of plunkers are very similar, they are created in the same way with minor exceptions.
|
||||
|
||||
To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlunker.js`. Thanks to them, the `builder.js` is as generic as possible.
|
||||
To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlunker.js`. Thanks to them,
|
||||
the `builder.js` is as generic as possible.
|
||||
|
||||
## Executing the plunker generation
|
||||
|
||||
|
|
@ -49,8 +68,11 @@ To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlu
|
|||
|
||||
Where? At `src/generated/live-examples/`.
|
||||
|
||||
Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the example.
|
||||
Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the
|
||||
example.
|
||||
|
||||
## Appendix: Why not generating plunkers at runtime?
|
||||
|
||||
At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool takes a few seconds to run, and the end result is only 3mb~.
|
||||
At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would
|
||||
need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool
|
||||
takes a few seconds to run, and the end result is only 3mb~.
|
||||
|
|
|
|||
|
|
@ -1,32 +1,36 @@
|
|||
# Overview
|
||||
|
||||
All the content that is rendered by the AIO application, and some of its configuration files, are generated from source files
|
||||
by [Dgeni](https://github.com/angular/dgeni). Dgeni is a general purpose documentation generation tool.
|
||||
All the content that is rendered by the AIO application, and some of its configuration files, are
|
||||
generated from source files by [Dgeni](https://github.com/angular/dgeni). Dgeni is a general purpose
|
||||
documentation generation tool.
|
||||
|
||||
Markdown files in `/aio/content`, code comments in the core Angular source files and example files are processed and transformed
|
||||
into files that are consumed by the AIO application.
|
||||
Markdown files in `/aio/content`, code comments in the core Angular source files and example files
|
||||
are processed and transformed into files that are consumed by the AIO application.
|
||||
|
||||
Dgeni is configured by "packages", which contain services and processors. Some of these packages are installed as `node_modules`
|
||||
from the [dgeni-packages](https://github.com/angular/dgeni-packages) and some are specific to the AIO project.
|
||||
Dgeni is configured by "packages", which contain services and processors. Some of these packages are
|
||||
installed as `node_modules` from the [dgeni-packages](https://github.com/angular/dgeni-packages) and
|
||||
some are specific to the AIO project.
|
||||
|
||||
The project specific packages are stored in the `aio/tools/transforms` folder. See the [README.md](plunker-builder/README.md)
|
||||
for more details.
|
||||
The project specific packages are stored in this folder (`aio/tools/transforms`).
|
||||
|
||||
If you are an author and want to know how to generate the documentation, the steps are outlined in the top level
|
||||
[README.md](../../README.md#guide-to-authoring).
|
||||
If you are an author and want to know how to generate the documentation, the steps are outlined in
|
||||
the top level [README.md](../../README.md#guide-to-authoring).
|
||||
|
||||
## Root packages
|
||||
|
||||
To run Dgeni, you must specify a root package, which acts as the entry point to the documentation generation.
|
||||
This root package, in turn requires a number of other packages, some are defined locally in the `tools/transforms` folder,
|
||||
such as `tools/transforms/cheatsheet-package` and `tools/transforms/content-package`, etc. And some are brought in from the
|
||||
`dgeni-packages` node modules, such as `jsdoc` and `nunjucks`.
|
||||
To run Dgeni, you must specify a root package, which acts as the entry point to the documentation
|
||||
generation.
|
||||
This root package, in turn requires a number of other packages, some are defined locally in the
|
||||
`tools/transforms` folder, such as `tools/transforms/cheatsheet-package` and
|
||||
`tools/transforms/content-package`, etc. And some are brought in from the `dgeni-packages` node
|
||||
modules, such as `jsdoc` and `nunjucks`.
|
||||
|
||||
* The primary root package is defined in `tools/transforms/angular.io-package/index.js`. This package is used to run a full
|
||||
generation of all the documentation.
|
||||
* There are also root packages defined in `tools/transforms/authors-package/*-package.js`. These packages are used by the
|
||||
documentation authors when writing docs, since it allows them to run partial doc generation, which is not complete but is
|
||||
faster for quickly seeing changes to the document that you are working on.
|
||||
* The primary root package is defined in `tools/transforms/angular.io-package/index.js`. This package
|
||||
is used to run a full generation of all the documentation.
|
||||
* There are also root packages defined in `tools/transforms/authors-package/*-package.js`. These
|
||||
packages are used by the documentation authors when writing docs, since it allows them to run partial
|
||||
doc generation, which is not complete but is faster for quickly seeing changes to the document that
|
||||
you are working on.
|
||||
|
||||
## Other packages
|
||||
|
||||
|
|
@ -41,3 +45,6 @@ faster for quickly seeing changes to the document that you are working on.
|
|||
* target-package
|
||||
|
||||
## Templates
|
||||
|
||||
All the templates for the angular.io dgeni transformations are stoted in the `tools/transforms/templates`
|
||||
folder. See the [README](./templates/README.md).
|
||||
|
|
@ -10,7 +10,8 @@ child. The template extension hierarchy looks like this (with declared blocks in
|
|||
|
||||
- layout/base.template.html (base)
|
||||
- module.template.html
|
||||
- layout/api-base.template.html (jumpNav, jumpNavLinks, whatItDoes, infoBar, securityConsiderations, deprecationNotes, howToUse, details)
|
||||
- layout/api-base.template.html (jumpNav, jumpNavLinks, whatItDoes, infoBar, securityConsiderations,
|
||||
deprecationNotes, howToUse, details)
|
||||
- class.template.html
|
||||
- directive.template.html
|
||||
- enum.template.html
|
||||
|
|
|
|||
Loading…
Reference in New Issue