From 930e559d1c4712049c7df81629aeb1ff29b05e8b Mon Sep 17 00:00:00 2001
From: Brandon <robertsbt@gmail.com>
Date: Thu, 26 Mar 2020 14:57:04 -0500
Subject: [PATCH] docs(angular): add overview page for Nx plugin for Angular
 (#2730)

---
 docs/angular/guides/plugin-overview.md | 98 ++++++++++++++++++++++++++
 docs/map.json                          |  4 ++
 2 files changed, 102 insertions(+)
 create mode 100644 docs/angular/guides/plugin-overview.md

diff --git a/docs/angular/guides/plugin-overview.md b/docs/angular/guides/plugin-overview.md
new file mode 100644
index 0000000000..89c6ed774c
--- /dev/null
+++ b/docs/angular/guides/plugin-overview.md
@@ -0,0 +1,98 @@
+# Nx Plugin for Angular
+
+The Nx Plugin for Angular contains builders, schematics, and utilities for managing Angular applications, and libraries within an Nx workspace. It provides:
+
+- Integration with libraries such as Jest, Cypress, Karma, Protractor, and Storybook.
+- Helper services, and functions to use along with NgRx libraries.
+- Scaffolding for upgrading AngularJS applications.
+- Scaffolding for creating buildable libraries that can be published to npm.
+- Utilities for automatic workspace refactoring.
+
+## Angular Projects in an Nx Workspace
+
+Building Angular applications within an Nx workspace is similar to building within a vanilla Angular CLI workspace, with a few differences.
+
+- Jest is used as the default unit test runner, configurable in the schematics section of the workspace configuration file.
+- Cypress is used as the default E2E test runner, configurable in the schematics section of the workspace configuration.
+- E2E tests are included in a separate project from the Angular application itself.
+- The Nx CLI delegates common commands such as build, serve, test, lint, and e2e to the Angular CLI.
+
+The file structure for an Angular application looks like:
+
+```treeview
+myorg/
+├── apps/
+│   ├── myapp/
+│   │   ├── src/
+│   │   │   ├── app/
+│   │   │   ├── assets/
+│   │   │   ├── environments/
+│   │   │   ├── favicon.ico
+│   │   │   ├── index.html
+│   │   │   ├── main.ts
+│   │   │   ├── polyfills.ts
+│   │   │   ├── styles.scss
+│   │   │   └── test.ts
+│   │   ├── browserslist
+│   │   ├── jest.conf.js
+│   │   ├── tsconfig.app.json
+│   │   ├── tsconfig.json
+│   │   ├── tsconfig.spec.json
+│   │   └── tslint.json
+│   └── myapp-e2e/
+│       ├── src/
+│       │   ├── fixtures/
+│       │   │   └── example.json
+│       │   ├── integration/
+│       │   │   └── app.spec.ts
+│       │   ├── plugins/
+│       │   │   └── index.ts
+│       │   └── support/
+│       │       ├── app.po.ts
+│       │       ├── commands.ts
+│       │       └── index.ts
+│       ├── cypress.json
+│       ├── tsconfig.e2e.json
+│       ├── tsconfig.json
+│       └── tslint.json
+├── libs/
+├── tools/
+├── angular.json
+├── nx.json
+├── package.json
+├── tsconfig.json
+├── tslint.json
+└── README.md
+```
+
+## See Also
+
+- [Using DataPersistence](/angular/guides/misc-data-persistence)
+- [Using NgRx](/angular/guides/misc-ngrx)
+- [Upgrading an AngularJS application to Angular](/angular/guides/misc-angular)
+
+## Builders
+
+- package - Bundles artifacts for a buildable library that can be distributed as an NPM package.
+
+## Schematics
+
+- [application](/angular/api/angular/schematics/application) - Create an Angular application
+- [downgrade-module](/angular/api/angular/schematics/downgrade-module) - Setup Downgrade Module
+- [karma](/angular/api/angular/schematics/karma) - Add karma configuration to a workspace
+- [karma-project](/angular/api/angular/schematics/karma-project) - Add karma testing to a project
+- [library](/angular/api/angular/schematics/library) - Create an Angular library
+- [move](/angular/api/angular/schematics/move) - Move an Angular application or library to another folder within the workspace
+- [ngrx](/angular/api/angular/schematics/ngrx) - Add and use NgRx for state management
+- [stories](/angular/api/angular/schematics/stories) - Create stories/specs for all components declared in a library
+- [storybook-configuration](/angular/api/angular/schematics/storybook-configuration) - Setup configuration for Storybook
+- [upgrade-module](/angular/api/angular/schematics/upgrade-module) - Add an upgrade module
+
+## Public API
+
+- DataPersistence - Angular Service that provides convenience methods for common operations of persisting data.
+- fetch - Handles data fetching, and correct ordering of fetching using NgRx Effects
+- navigation - Handles data fetching based on navigating to a certain component using NgRx Effects
+- optimisticUpdate - Handles optimistic updates (updating the client first) using NgRx Effects.
+- pessimisticUpdate - Handles pessimistic updates (updating the server first) fetching using NgRx Effects.
+  NxModule - An NgModule used to register the Angular providers, including DataPersistence.
diff --git a/docs/map.json b/docs/map.json
index 233de5b390..d07c6adad3 100644
--- a/docs/map.json
+++ b/docs/map.json
@@ -330,6 +330,10 @@
             "name": "angular",
             "id": "angular",
             "itemList": [
+              {
+                "id": "plugin-overview",
+                "name": "Overview"
+              },
               {
                 "id": "schematics",
                 "name": "Schematics",