From 28a80e6e051f34fcb9888f23db732d2804ca4783 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Sat, 15 Jul 2017 16:38:10 +0100 Subject: [PATCH] docs(aio): high-level documentation of AIO tooling (#18151) PR Close #18151 --- aio/tools/README.md | 69 +++++++++++++++++++++++++++++ aio/tools/cli-patches/README.md | 6 +++ aio/tools/example-zipper/README.md | 4 ++ aio/tools/examples/README.md | 10 +++++ aio/tools/plunker-builder/README.md | 10 +++++ 5 files changed, 99 insertions(+) create mode 100644 aio/tools/README.md create mode 100644 aio/tools/cli-patches/README.md create mode 100644 aio/tools/example-zipper/README.md create mode 100644 aio/tools/examples/README.md create mode 100644 aio/tools/plunker-builder/README.md diff --git a/aio/tools/README.md b/aio/tools/README.md new file mode 100644 index 0000000000..219750fa51 --- /dev/null +++ b/aio/tools/README.md @@ -0,0 +1,69 @@ +# AIO project tooling + +This document gives an overview of the tools that we use to generate the content for the angular.io website. + +The application that actually renders this content can be found in the `/aio/src` folder. +The handwritten content can be found in the `/aio/content` folder. + +Each subfolder in this `/aio/tools/` folder contains a self-contained tool and its configuration. There is +a `README.md` file in each folder that describes the tool in more detail. + +## cli-patches + +The AIO application is built using the Angular CLI tool. We are often trialling new features for the CLI, which +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. + +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. + +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. +* 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. + +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. + +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. + +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. + +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 diff --git a/aio/tools/cli-patches/README.md b/aio/tools/cli-patches/README.md new file mode 100644 index 0000000000..eec5f43e50 --- /dev/null +++ b/aio/tools/cli-patches/README.md @@ -0,0 +1,6 @@ +# Overview + +The AIO application is built using the Angular CLI tool. We are often trialling new features for the CLI, which +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. + diff --git a/aio/tools/example-zipper/README.md b/aio/tools/example-zipper/README.md new file mode 100644 index 0000000000..96bf8d1311 --- /dev/null +++ b/aio/tools/example-zipper/README.md @@ -0,0 +1,4 @@ +# 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. \ No newline at end of file diff --git a/aio/tools/examples/README.md b/aio/tools/examples/README.md new file mode 100644 index 0000000000..61b98bff84 --- /dev/null +++ b/aio/tools/examples/README.md @@ -0,0 +1,10 @@ +# 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. + +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. \ No newline at end of file diff --git a/aio/tools/plunker-builder/README.md b/aio/tools/plunker-builder/README.md new file mode 100644 index 0000000000..77966ee47e --- /dev/null +++ b/aio/tools/plunker-builder/README.md @@ -0,0 +1,10 @@ +# Overview + +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.