docs: initial check-in for ngrx.io project (#1320)

package.json

@@ -46,7 +46,10 @@
   ],
   "author": "Rob Wormald <[email protected]>",
   "license": "MIT",
-  "repository": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ngrx/platform.git"
+  },
   "nyc": {
     "extension": [
       ".ts"

projects/ngrx.io/.gitignore

@@ -0,0 +1,49 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# compiled output
+/dist
+/out-tsc
+/src/generated
+/tmp
+
+# dependencies
+/node_modules
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# misc
+/.sass-cache
+/connect.lock
+/coverage
+/libpeerconnection.log
+debug.log
+npm-debug.log
+testem.log
+/typings
+yarn-error.log
+
+# e2e
+/e2e/*.js
+/e2e/*.map
+protractor-results*.txt
+
+# System Files
+.DS_Store
+Thumbs.db
+
+# copied dependencies
+src/assets/js/lunr*

projects/ngrx.io/README.md

@@ -0,0 +1,120 @@
+# NgRx documentation project (https://ngrx.io)
+
+Everything in this folder is part of the documentation project. This includes
+
+- the web site for displaying the documentation
+- the dgeni configuration for converting source files to rendered files that can be viewed in the web site.
+- the tooling for setting up examples for development; and generating live-example and zip files from the examples.
+
+## Developer tasks
+
+We use [Yarn](https://yarnpkg.com) to manage the dependencies and to run build tasks.
+You should run all these tasks from the `projects/ngrx.io` folder.
+Here are the most important tasks you might need to use:
+
+- `yarn` - install all the dependencies.
+- `yarn setup` - install all the dependencies, boilerplate, stackblitz, zips and run dgeni on the docs.
+
+- `yarn build` - create a production build of the application (after installing dependencies, boilerplate, etc).
+
+- `yarn start` - run a development web server that watches the files; then builds the doc-viewer and reloads the page, as necessary.
+- `yarn serve-and-sync` - run both the `docs-watch` and `start` in the same console.
+- `yarn lint` - check that the doc-viewer code follows our style rules.
+- `yarn test` - watch all the source files, for the doc-viewer, and run all the unit tests when any change.
+- `yarn test --watch=false` - run all the unit tests once.
+- `yarn e2e` - run all the e2e tests for the doc-viewer.
+
+- `yarn docs` - generate all the docs from the source files.
+- `yarn docs-watch` - watch the Angular source and the docs files and run a short-circuited doc-gen for the docs that changed.
+- `yarn docs-lint` - check that the doc gen code follows our style rules.
+- `yarn docs-test` - run the unit tests for the doc generation code.
+
+- `yarn boilerplate:add` - generate all the boilerplate code for the examples, so that they can be run locally. Add the option
+- `yarn boilerplate:remove` - remove all the boilerplate code that was added via `yarn boilerplate:add`.
+- `yarn generate-stackblitz` - generate the stackblitz files that are used by the `live-example` tags in the docs.
+- `yarn generate-zips` - generate the zip files from the examples. Zip available via the `live-example` tags in the docs.
+
+- `yarn example-e2e` - run all e2e tests for examples
+
+  - `yarn example-e2e --setup` - force webdriver update & other setup, then run tests
+  - `yarn example-e2e --filter=foo` - limit e2e tests to those containing the word "foo"
+  - `yarn example-e2e --setup --local` - run e2e tests with the local version of Angular contained in the "dist" folder
+
+- `yarn build-ie-polyfills` - generates a js file of polyfills that can be loaded in Internet Explorer.
+
+## Using ServiceWorker locally
+
+Running `yarn start` (even when explicitly targeting production mode) does not set up the
+ServiceWorker. If you want to test the ServiceWorker locally, you can use `yarn build` and then
+serve the files in `dist/` with `yarn http-server dist -p 4200`.
+
+## Guide to authoring
+
+There are two types of content in the documentation:
+
+- **API docs**: descriptions of the modules, classes, interfaces, decorators, etc that make up the Angular platform.
+  API docs are generated directly from the source code.
+  The source code is contained in TypeScript files, located in the `modules` folder.
+  Each API item may have a preceding comment, which contains JSDoc style tags and content.
+  The content is written in markdown.
+
+- **Other content**: guides, tutorials, and other marketing material.
+  All other content is written using markdown in text files, located in the `projects/ngrx.io/content` folder.
+  More specifically, there are sub-folders that contain particular types of content: guides, and marketing.
+
+- **Code examples**: code examples need to be testable to ensure their accuracy.
+  Also, our examples have a specific look and feel and allow the user to copy the source code. For larger
+  examples they are rendered in a tabbed interface (e.g. template, HTML, and TypeScript on separate
+  tabs).
+
+We use the [dgeni](https://github.com/angular/dgeni) tool to convert these files into docs that can be viewed in the doc-viewer.
+
+### Generating the complete docs
+
+The main task for generating the docs is `yarn docs`. This will process all the source files (API and other),
+extracting the documentation and generating JSON files that can be consumed by the doc-viewer.
+
+### Partial doc generation for editors
+
+Full doc generation can take up to one minute. That's too slow for efficient document creation and editing.
+
+You can make small changes in a smart editor that displays formatted markdown:
+
+> In VS Code, _Cmd-K, V_ opens markdown preview in side pane; _Cmd-B_ toggles left sidebar
+
+You also want to see those changes displayed properly in the doc viewer
+with a quick, edit/view cycle time.
+
+For this purpose, use the `yarn docs-watch` task, which watches for changes to source files and only
+re-processes the the files necessary to generate the docs that are related to the file that has changed.
+Since this task takes shortcuts, it is much faster (often less than 1 second) but it won't produce full
+fidelity content. For example, links to other docs and code examples may not render correctly. This is
+most particularly noticed in links to other docs and in the embedded examples, which may not always render
+correctly.
+
+The general setup is as follows:
+
+- Open a terminal, ensure the dependencies are installed; run an initial doc generation; then start the doc-viewer:
+
+```bash
+yarn setup
+yarn start
+```
+
+- Open a second terminal and start watching the docs
+
+```bash
+yarn docs-watch
+```
+
+> Alternatively, try the consolidated `serve-and-sync` command that builds, watches and serves in the same terminal window
+
+```bash
+yarn serve-and-sync
+```
+
+- Open a browser at https://localhost:4200/ and navigate to the document on which you want to work.
+  You can automatically open the browser by using `yarn start -o` in the first terminal.
+
+- Make changes to the page's associated doc or example files. Every time a file is saved, the doc will
+  be regenerated, the app will rebuild and the page will reload.

projects/ngrx.io/angular.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "./node_modules/@angular-devkit/core/src/workspace/workspace-schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "yarn"
+  },
+  "newProjectRoot": "projects",
+  "projects": {
+    "site": {
+      "root": "",
+      "sourceRoot": "src",
+      "projectType": "application",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:browser",
+          "options": {
+            "outputPath": "dist",
+            "index": "src/index.html",
+            "main": "src/main.ts",
+            "tsConfig": "src/tsconfig.app.json",
+            "aot": true,
+            "optimization": true,
+            "buildOptimizer": true,
+            "outputHashing": "all",
+            "sourceMap": true,
+            "statsJson": true,
+            "extractCss": true,
+            "extractLicenses": true,
+            "namedChunks": true,
+            "vendorChunk": false,
+            "polyfills": "src/polyfills.ts",
+            "assets": [
+              "src/assets",
+              "src/generated",
+              "src/app/search/search-worker.js",
+              "src/pwa-manifest.json",
+              "src/google385281288605d160.html",
+              {
+                "glob": "custom-elements.min.js",
+                "input": "node_modules/@webcomponents/custom-elements",
+                "output": "/assets/js"
+              },
+              {
+                "glob": "native-shim.js",
+                "input": "node_modules/@webcomponents/custom-elements/src",
+                "output": "/assets/js"
+              }
+            ],
+            "styles": [
+              "src/styles.scss"
+            ],
+            "scripts": []
+          },
+          "configurations": {
+            "fast": {
+              "optimization": false
+            },
+            "next": {
+              "fileReplacements": [
+                {
+                  "src": "src/environments/environment.ts",
+                  "replaceWith": "src/environments/environment.next.ts"
+                }
+              ],
+              "serviceWorker": true
+            },
+            "stable": {
+              "fileReplacements": [
+                {
+                  "src": "src/environments/environment.ts",
+                  "replaceWith": "src/environments/environment.stable.ts"
+                }
+              ],
+              "serviceWorker": true
+            },
+            "archive": {
+              "fileReplacements": [
+                {
+                  "src": "src/environments/environment.ts",
+                  "replaceWith": "src/environments/environment.archive.ts"
+                }
+              ],
+              "serviceWorker": true
+            }
+          }
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "options": {
+            "browserTarget": "site:build"
+          },
+          "configurations": {
+            "fast": {
+              "browserTarget": "site:build:fast"
+            },
+            "next": {
+              "browserTarget": "site:build:next"
+            },
+            "stable": {
+              "browserTarget": "site:build:stable"
+            },
+            "archive": {
+              "browserTarget": "site:build:archive"
+            }
+          }
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n",
+          "options": {
+            "browserTarget": "site:build"
+          }
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "main": "src/test.ts",
+            "karmaConfig": "src/karma.conf.js",
+            "polyfills": "src/polyfills.ts",
+            "tsConfig": "src/tsconfig.spec.json",
+            "scripts": [],
+            "styles": [
+              "src/styles.scss"
+            ],
+            "assets": [
+              "src/assets",
+              "src/generated",
+              "src/app/search/search-worker.js",
+              "src/pwa-manifest.json",
+              "src/google385281288605d160.html",
+              {
+                "glob": "custom-elements.min.js",
+                "input": "node_modules/@webcomponents/custom-elements",
+                "output": "/assets/js"
+              },
+              {
+                "glob": "native-shim.js",
+                "input": "node_modules/@webcomponents/custom-elements/src",
+                "output": "/assets/js"
+              }
+            ]
+          }
+        },
+        "lint": {
+          "builder": "@angular-devkit/build-angular:tslint",
+          "options": {
+            "tsConfig": [
+              "src/tsconfig.app.json",
+              "src/tsconfig.spec.json"
+            ],
+            "exclude": []
+          }
+        }
+      }
+    },
+    "site-e2e": {
+      "root": "",
+      "projectType": "application",
+      "cli": {},
+      "schematics": {},
+      "architect": {
+        "e2e": {
+          "builder": "@angular-devkit/build-angular:protractor",
+          "options": {
+            "protractorConfig": "tests/e2e/protractor.conf.js",
+            "devServerTarget": "site:serve"
+          }
+        },
+        "lint": {
+          "builder": "@angular-devkit/build-angular:tslint",
+          "options": {
+            "tsConfig": [
+              "tests/e2e/tsconfig.e2e.json"
+            ],
+            "exclude": []
+          }
+        }
+      }
+    }
+  },
+  "schematics": {
+    "@schematics/angular:component": {
+      "inlineStyle": true,
+      "prefix": "aio",
+      "styleext": "scss"
+    },
+    "@schematics/angular:directive": {
+      "prefix": "aio"
+    }
+  }
+}