docs(aio): high-level documentation of the `transforms` folder (#18151)

PR Close #18151

aio/tools/transforms/README.md

@@ -1,27 +1,43 @@
-# Documentation Generation
+# Overview
 
-The dgeni tool is used to generate the documentation from the source files held in this repository.
-The documentation generation is configured by a dgeni package defined in `tools/transforms/angular.io-package/index.js`.
-This package, in turn requires a number of other packages, some are defined locally in the `tools/transforms` folder,
+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.
+
+If you are an author and want to know how to generate the documentation, the steps are outlined in the top level
+[README.md](../../README.md#guide-to-authoring).
+
+## Root packages
+
+To run Dgeni, you must specify a root package, which acts as the entry point to the documentation generation.
+This root package, in turn requires a number of other packages, some are defined locally in the `tools/transforms` folder,
 such as `tools/transforms/cheatsheet-package` and `tools/transforms/content-package`, etc. And some are brought in from the
 `dgeni-packages` node modules, such as `jsdoc` and `nunjucks`.
 
-## Generating the docs
+* The primary root package is defined in `tools/transforms/angular.io-package/index.js`. This package is used to run a full
+generation of all the documentation.
+* There are also root packages defined in `tools/transforms/authors-package/*-package.js`. These packages are used by the
+documentation authors when writing docs, since it allows them to run partial doc generation, which is not complete but is
+faster for quickly seeing changes to the document that you are working on.
 
-To generate the documentation simply run `yarn docs` from the command line.
+## Other packages
 
-## Testing the dgeni packages
+* angular-base-package
+* angular-api-package
+* angular-content-package
+* content-package
+* examples-package
+* links-package
+* post-process-package
+* remark-package
+* target-package
 
-The local packages have unit tests that you can execute by running `yarn docs-test` from the command line.
-
-## What does it generate?
-
-The output from dgeni is written to files in the `src/generated` folder.
-
-Notably this includes a JSON file containing the partial HTML for each "page" of the documentation, such as API pages and guides.
-It also includes JSON files that contain metadata about the documentation such as navigation data and
-keywords for building a search index.
-
-## Viewing the docs
-
-You can view the pages by running `yarn start` and navigating to https://localhost:4200.
+## Templates

aio/tools/transforms/templates/README.md

@@ -26,119 +26,6 @@ child. The template extension hierarchy looks like this (with declared blocks in
 # Doc Properties
 
 It is useful to know what properties are available on each doc type when working with the templates.
-Here is an overview:
-
-## class
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-- members
-
-## directive
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-- members
-
-## enum
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
-## var
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
-## const
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
-## let
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
-## decorator
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-- members
-
-## function
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
-## interface
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-- members
-
-## type-alias
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
-## pipe
-
-- docType
-- name
-- id
-- moduleDoc
-- path
-- description
-- notYetDocumented
-
+The `typescript` Dgeni package is now written in TypeScript and there is a class for each of the types of
+API document. See https://github.com/angular/dgeni-packages/tree/master/typescript/src/api-doc-types.
+This is a good place to go to see what properties you can use in the templates.