From 4530654501c556609a8635bb32363ed019abdb2a Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Sat, 15 Jul 2017 17:31:48 +0100 Subject: [PATCH] docs(aio): high-level documentation of the `transforms` folder (#18151) PR Close #18151 --- aio/tools/transforms/README.md | 56 +++++++---- aio/tools/transforms/templates/README.md | 119 +---------------------- 2 files changed, 39 insertions(+), 136 deletions(-) diff --git a/aio/tools/transforms/README.md b/aio/tools/transforms/README.md index 768ba58c19..e48fe2d948 100644 --- a/aio/tools/transforms/README.md +++ b/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 diff --git a/aio/tools/transforms/templates/README.md b/aio/tools/transforms/templates/README.md index 68bed6350b..22c82bbfc9 100644 --- a/aio/tools/transforms/templates/README.md +++ b/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. \ No newline at end of file