diff --git a/aio/tools/README.md b/aio/tools/README.md index 219750fa51..ea88533db2 100644 --- a/aio/tools/README.md +++ b/aio/tools/README.md @@ -65,5 +65,5 @@ 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. -The project specific packages are stored in the `aio/tools/transforms` folder. See the [README.md](plunker-builder/README.md) -for more details. \ No newline at end of file +The project specific packages are stored in the `aio/tools/transforms` folder. See the [README.md](transforms/README.md) +for more details. diff --git a/aio/tools/example-zipper/README.md b/aio/tools/example-zipper/README.md index 15c0d7f092..784e32232d 100644 --- a/aio/tools/example-zipper/README.md +++ b/aio/tools/example-zipper/README.md @@ -4,7 +4,7 @@ In the AIO application, we offer the reader the option to download each example ## 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 a 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 { @@ -21,11 +21,11 @@ The `exampleZipper.js` tool is very similar to the Plunker's `builder.js`. The The zipper will use this information for creating new zips. -## Three kind of examples +## 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 boilerplate uses a `package.json` that contains packages and scripts tags 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. @@ -40,7 +40,7 @@ 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. @@ -48,11 +48,11 @@ The tool will also give some standard names to the scripts. 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 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" -In both `plnkr.json` and `zipper.json` you can use two new properties: +In both `plnkr.json` and `zipper.json` you can use two extra properties for the zipper configuration: ``` { @@ -62,12 +62,12 @@ In both `plnkr.json` and `zipper.json` you can use two new properties: } ``` -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 -`generateSipz.js` will create a zip for each `plnk.json` or `zipper.json` it finds. +`generateZips.js` will create a zip for each `plnkr.json` or `zipper.json` it finds. -Where? at `src/generated/zips/`. +Where? At `src/generated/zips/`. Then the `` embedded component will look at this folder to get the zip it needs for the example. diff --git a/aio/tools/examples/README.md b/aio/tools/examples/README.md index 7fb5e94993..c8119deec0 100644 --- a/aio/tools/examples/README.md +++ b/aio/tools/examples/README.md @@ -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 diff --git a/aio/tools/plunker-builder/README.md b/aio/tools/plunker-builder/README.md index 19c9b8a64e..b87df04ede 100644 --- a/aio/tools/plunker-builder/README.md +++ b/aio/tools/plunker-builder/README.md @@ -10,13 +10,15 @@ Both flavours are created within `builder.js`. How is a plunker created? What is An "executable" plunker is an HTML file with a `
` that makes a post to plunker on submit. It contains an `` 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. + 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 an 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 do this tool know about 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: @@ -37,18 +39,18 @@ Here you can specify a description for the plunker, some tags, a basePath and al ## Classic plunkers and embedded ones -Luckily, both kind of plunkers are very similar, the are created in the same way with a minor exceptions. +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. ## Executing the plunker generation -`generatePlunkers.js` will create a classic plunker and a embedded plunker for each `plnk.json` it finds. +`generatePlunkers.js` will create a classic plunker and an embedded plunker for each `plnkr.json` it finds. -Where? at `src/generated/live-examples/`. +Where? At `src/generated/live-examples/`. Then the `` embedded component will look at this folder to get the plunker it needs for the example. -## Appendix: Why not generating plunkers on runtime? +## 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~.