docs: add missing Cypress to leftnav (#2082)

Also
- fix link to my Bazel Leaving Labs post
- don't point to generated API doc for angular/bazel package as that makes leftnav confusing
- add some more explanation to Angular/React tradeoffs section

docs/BUILD.bazel

@@ -55,6 +55,7 @@ genrule(
 
 _PACKAGE_READMES = {
     "Built-ins": ":builtins.doc",
+    "Cypress": "//packages/cypress:README.md",
     "Jasmine": "//packages/jasmine:README.md",
     "Karma": "//packages/karma:README.md",
     "Protractor": "//packages/protractor:README.md",

docs/Cypress.md

@@ -0,0 +1,128 @@
+---
+title: Cypress
+layout: default
+stylesheet: docs
+---
+<!-- *********************
+ DO NOT EDIT THIS FILE
+  It is a generated build output from Stardoc.
+  Instead you must edit the .bzl file where the rules are declared,
+  or possibly a markdown file next to the .bzl file
+ ********************* -->
+# Cypress rules for Bazel
+
+The Cypress rules run tests under the Cypress e2e testing framework with Bazel.
+
+
+## Installation
+
+Add `@bazel/cypress`, `cypress` and `@cypress/browserify-preprocessor` npm packages to your `devDependencies` in `package.json`.
+
+```
+npm install --save-dev @bazel/cypress cypress @cypress/browserify-preprocessor
+```
+or using yarn
+```
+yarn add -D @bazel/cypress cypress @cypress/browserify-preprocessor
+```
+
+Then, load and invoke `cypress_repository` within your `WORKSPACE` file.
+
+```python
+# Assuming your external repository for node_modules is named @npm
+
+load("@npm//@bazel/cypress:index.bzl", "cypress_repository")
+
+# The name you pass here names the external repository you can load cypress_web_test from
+cypress_repository(name = "cypress")
+```
+
+
+### macOS install requirements
+On macOS, `cypress_repository` generates an external repository containing files whose names contain spaces. In order to make these files compatible with bazel you will need to add the following flag to your `.bazelrc` file:
+```python
+# Required for cypress_repository on macOS
+build --experimental_inprocess_symlink_creation
+```
+
+
+### windows install requirements
+At this point in time, `cypress_repository` is incompatible with bazel sandboxing on Windows. This may change in the future, but for now using cypress on windows requires windows sandboxing be disabled (it is disabled by default)
+
+
+## Example use of cypress_web_test
+This example assumes you've named your external repository for node_modules as `npm` and for cypress as `cypress` 
+```python
+load("@cypress//:index.bzl", "cypress_web_test")
+load("@npm//@bazel/typescript:index.bzl", "ts_library")
+
+# You must create a cypress plugin in order to boot a server to serve your application. It can be written as a javascript file or in typescript using ts_library or ts_project.
+ts_library(
+    name = "plugins_file",
+    testonly = True,
+    srcs = ["plugin.ts"],
+    tsconfig = ":tsconfig.json",
+    deps = [
+        "@npm//@types/node",
+        "@npm//express",
+    ],
+)
+
+# You can write your cypress tests a javascript files or in typescript using ts_library or ts_project.
+ts_library(
+    name = "hello_spec",
+    testonly = True,
+    srcs = ["hello.spec.ts"],
+    tsconfig = ":tsconfig.json",
+    deps = [
+        "@npm//cypress",
+    ],
+)
+
+cypress_web_test(
+    # The name of your test target
+    name = "test",
+    srcs = [
+        # Load javascript test files directly as sources
+        "world.spec.js",
+        # Load ts_library tests as a target to srcs
+        ":hello_spec",
+    ],
+    # A cypress config file is required
+    config_file = "cypress.json",
+    # Any runtime dependencies you need to boot your server or run your tests
+    data = [],
+    # Your cypress plugin used to configure cypress and boot your server
+    plugins_file = ":plugins_file",
+)
+```[name]: https://bazel.build/docs/build-ref.html#name
+[label]: https://bazel.build/docs/build-ref.html#labels
+[labels]: https://bazel.build/docs/build-ref.html#labels
+
+
+## cypress_repository
+
+
+
+
+### Usage
+
+```
+cypress_repository(name, cypress_bin, quiet)
+```
+
+
+
+#### `name`
+(*[name], mandatory*): A unique name for this repository.
+
+#### `cypress_bin`
+(*[label]*): bazel target of the cypress binary
+
+Defaults to `@npm//:node_modules/cypress/bin/cypress`
+
+#### `quiet`
+(*Boolean*): If stdout and stderr should be printed to the terminal
+
+Defaults to `True`
+

docs/_includes/drawer.html

@@ -41,12 +41,13 @@
         <li>
           <span class="drawer-nav-title">Frameworks</span>
           <ul>
-            <li><a href="https://angular.github.io/bazel-builds/">Angular<i class="material-icons">launch</i></a></li>
+            <li><a href="examples.html#angular">Angular</a></li>
           </ul>
         </li>
         <li>
           <span class="drawer-nav-title">Testing</span>
           <ul>
+            <li><a href="Cypress.html">Cypress</a></li>
             <li><a href="Karma.html">Karma</a></li>
             <li><a href="Protractor.html">Protractor</a></li>
             <li><a href="Jasmine.html">Jasmine</a></li>

docs/examples.md

@@ -9,20 +9,28 @@ stylesheet: docs
 ## Angular
 
 Bazel can run any toolchain you want, so there is more than one way to use it with Angular.
-See Alex's post [Angular ❤️ Bazel update](https://dev.to/bazel/angular-bazel-update-n33-temp-slug-9563533?preview=d98c4fd0c1ad788b7f3e01eaf716c5b249d68b976a8697d07815023747be3b8f3277c2b182df7682a4efb81fac76056244b3ce9f7445110c70971bf8) for a longer explanation.
+See Alex's post [Angular ❤️ Bazel update](https://dev.to/bazel/angular-bazel-leaving-angular-labs-51ja) for a longer explanation.
 
-**Architect**: The first approach is the simplest: use Architect (aka. Angular CLI Builders). This is the build tool inside of Angular CLI, so your existing application will continue to work the same way. However, it has the worst performance because the level of incrementality is only as fine as how many libs your application is composed from.
+**Architect**: The first approach is the simplest: use Architect (aka. Angular CLI Builders). This is the build tool inside of Angular CLI, so your existing application will continue to work the same way, and you can still get support from the Angular team. This may be a good choice if your goal is just to include an Angular app in a full-stack Bazel build that includes your backend, and making the Angular build&test faster is not important for you.
+
+However, it has the worst performance because the level of incrementality is only as fine as how many libs your application is composed from.
+Bazel can only make a build more parallel and incremental if you express a wider dependency graph to it.
 
 Example: [examples/angular_bazel_architect](https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_bazel_architect)
 
-**Google**: This toolchain is what we originally advertised as "Angular, Bazel and CLI" (ABC). It is based on Google's internal toolchain for building Angular, and has good performance characteristics. However it is harder to migrate to, because it doesn't have good compatibility for existing applications.
+**Google**: This toolchain is what we originally advertised as "Angular Buildtools Convergence" (ABC). It is based on Google's internal toolchain for building Angular, and has good performance characteristics. However it is harder to migrate to, because it doesn't have good compatibility for existing applications.
 
 The example has its own guide: [examples/angular](https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular)
 
 **View Engine**: If you're stuck on the older Angular compiler/runtime before Ivy, called View Engine, then your options are more limited. We don't support Angular 9 + View Engine + Bazel.
 
 Example: [examples/angular_view_engine](https://github.com/bazelbuild/rules_nodejs/tree/stable/examples/angular_view_engine)
 
+**Custom**: Bazel is excellent for advanced use cases where you need to customize your toolchain.
+Take any off-the-shelf tools, follow their README's to call their CLI, and assemble them together in a custom way.
+This lets you take advantage of the latest JS ecosystem innovations without waiting for tooling vendors to
+assemble it all together for you.
+
 ## React
 
 Similar to the explanation above for Angular, Bazel is agnostic to what tools you choose to run on your project.
@@ -40,8 +48,11 @@ The [create-react-app example](https://github.com/bazelbuild/rules_nodejs/tree/s
 shows how this will look. We suggest reading the README in that example, and also look at the commit history to that
 directory as an illustration of how we started from create-react-app and added Bazel bits.
 
-**cra-eject**: As a next step to make our Build more incremental and performant, we follow the create-react-app suggestion
-of "ejecting" the configuration. This means the `react-scripts` build system is gone, and Bazel can take its place.
+**react-scripts-like**: As a next step to make our Build more incremental and performant, we can replace the `react-scripts` build system with Bazel, but preserve compatibility as much as possible by having Bazel run
+mostly the same tools with mostly identical configuration. We continue to transpile TS to JS using Babel, for example,
+but we do it in a build step before invoking Webpack, just using the Babel CLI.
+
+This is a good middle ground to get some benefits from Bazel while staying on the same supported tools as react-scripts.
 
 TODO(alexeagle): build an example illustrating how this looks