History

George Kalpakas 671deadde1 fix(docs-infra): avoid version mismatch error when using local Angular packages (#34213 ) The local Angular packages used to build `aio/` when running `yarn setup-local`/`yarn build-local` (and related commands), are built by bazel. Bazel, determines the version to use for these locally built packages based on the latest tag for a commit on the current branch. (This works as expected during the release, because the packages are built on the correct branch with up-to-date tags.) During local development, however, this often leads to generating older versions than what the current `@angular/cli` version is compatible with, if the user has not fetched the latest tags from `angular/angular` or the branch has not been rebased recently. Previously, the above (common) situation would result in a build error by the CLI. (Note that this would be a false error, because in this case the version set by bazel would not reflect the actual version of the local packages.) The solution would be for the user to fetch the latest tags from `angular/angular`, rebase their branch and run a bazel build again (ensuring that it would actually build anew and not emit cached artifacts). This was cumbersome and most people didn't even know about it. This commit avoids this error and the associated pain-points by overwriting the versions of the installed local packages with fake versions based on the ones in the lockfile, which are guaranteed to be compatible with the currently used CLI version. Fixes #34208 PR Close #34213		2019-12-03 10:40:14 -08:00
..
cli-patches	build(aio): update to @angular/cli@6.0.0-rc.2 + project layout update (#23234 )	2018-04-17 14:09:02 -07:00
example-zipper	build(docs-infra): correct list of files included in ZIPs to match current layout (#31937 )	2019-08-05 09:54:52 -07:00
examples	test(docs-infra): ensure RxJS-related docs examples can compile without errors (#34063 )	2019-12-02 11:02:13 -08:00
firebase-test-utils	build(docs-infra): enable more TypeScript strictness flags (#32980 )	2019-10-10 13:56:14 -07:00
ng-packages-installer	fix(docs-infra): avoid version mismatch error when using local Angular packages (#34213 )	2019-12-03 10:40:14 -08:00
stackblitz-builder	docs(docs-infra): fix typos and spelling in the stackblitz-builder/README.md (#34009 )	2019-11-25 11:39:05 -05:00
transforms	docs: add deprecated-api-item class to deprecated items (#34088 )	2019-12-02 11:03:05 -08:00
README.md	build: remove travisci leftovers (#27979 )	2019-01-09 10:41:16 -08:00
RELEASE.md	fix(aio): remove remaining `plnkr` references (#20165 )	2018-01-23 21:30:27 -08:00
tslint.json	refactor: remove tslint no-use-before-declare rule (#30288 )	2019-05-07 10:25:36 -07:00

README.md

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 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 CI 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:

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 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 for more details.

stackblitz-builder

In the AIO application, we can embed a running version of the example as a Stackblitz session. We can also provide a link to create a runnable version of the example in the Stackblitz editor.

See the 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. 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 and some are specific to the AIO project.

The project specific packages are stored in the aio/tools/transforms folder. See the README.md for more details.