cargdev/angular
1
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(aio): applying some feedback (#18151)

Browse Source 
PR Close #18151
This commit is contained in:
Jesus Rodriguez
2017-07-31 13:34:22 +02:00
committed by Igor Minar
parent 526a67f8f4
commit 5bca58e748
4 changed files with 27 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
aio/tools/examples/README.md
View File

@ -6,7 +6,7 @@ In order to build, run and test these examples independently we need to install
## Boilerplate overview
As mentioned, many of the documentation pages contains 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.
@ -18,17 +18,17 @@ 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 `-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 script tags, 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.
* **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 when the tool runs, it finds **all** the folders with a `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:
@ -46,7 +46,7 @@ In this case, this would indicate that this is a CLI example. Won't make any dif
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 this 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.
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
@ -56,9 +56,9 @@ This tool expects all the examples to be build with `npm run build`. If an examp
### add-example-boilerplate.js
This script install 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 doesn'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