docs(docs-infra): apply the one-sentence-per-line rule to Markdown files in `aio/tools/` (#38992)
This commit updates the Markdown files inside the `aio/tools/` directory to contain one sentence per line in order to be consistent with how Markdown files are formatted in the rest of the repo. PR Close #38992
This commit is contained in:
George Kalpakas
Alex Rickabaugh
parent
ded9aeb447
commit
efe0e03fe1
|
|
@ -39,31 +39,27 @@ See the [README.md](examples/README.md) for more details.
|
|||
|
||||
## example-zipper
|
||||
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained
|
||||
runnable project packaged as a zip file. These zip files are generated by the utility in this folder.
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project packaged as a zip file.
|
||||
These zip files are generated by the utility in this folder.
|
||||
|
||||
See the [README.md](example-zipper/README.md) for more details.
|
||||
|
||||
## stackblitz-builder
|
||||
|
||||
In the AIO application, we can embed a running version of the example as a [Stackblitz](https://stackblitz.com/) session.
|
||||
We can also provide a link to create a runnable version of the example in the [Stackblitz](https://stackblitz.com/)
|
||||
editor.
|
||||
We can also provide a link to create a runnable version of the example in the [Stackblitz](https://stackblitz.com/) editor.
|
||||
|
||||
See the [README.md](stackblitz-builder/README.md) for more details.
|
||||
|
||||
## transforms
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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](transforms/README.md) for more details.
|
||||
The project specific packages are stored in the `aio/tools/transforms` folder.
|
||||
See the [README.md](transforms/README.md) for more details.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# Docs releases
|
||||
|
||||
This document explains how to update the documentation examples after an Angular release. This is only needed for major and minor versions.
|
||||
This document explains how to update the documentation examples after an Angular release.
|
||||
This is only needed for major and minor versions.
|
||||
|
||||
All the packages for the docs' examples are specified in `/aio/tools/examples/shared/package.json`
|
||||
|
||||
|
|
@ -12,5 +13,5 @@ $ yarn upgrade-interactive --tilde
|
|||
|
||||
There, select all the packages that are updated on the new Angular release.
|
||||
|
||||
**2)** Changes to the tsconfig.json? There are several files in `/aio/tools/examples/shared/boilerplate/*/tsconfig.json` (based on the example type).
|
||||
|
||||
**2)** Changes to the tsconfig.json?
|
||||
There are several files in `/aio/tools/examples/shared/boilerplate/*/tsconfig.json` (based on the example type).
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
# Overview
|
||||
|
||||
The AIO application is built using the Angular CLI tool. We are often trialling new features for the CLI, which
|
||||
we apply to the library after it is installed. This folder contains git patch files that contain these new features
|
||||
and a utility to apply those patches to the CLI library.
|
||||
The AIO application is built using the Angular CLI tool. We are often trialling new features for the CLI, which we apply to the library after it is installed. This folder contains git patch files that contain these new features and a utility to apply those patches to the CLI library.
|
||||
|
||||
**Currently, we have no patches to run.**
|
||||
**Currently, we have no patches to run.**
|
||||
|
|
|
|||
|
|
@ -1,13 +1,14 @@
|
|||
# Overview
|
||||
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained
|
||||
runnable project packaged as a zip file. These zip files are generated by the utility in this folder.
|
||||
In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project packaged as a zip file.
|
||||
These zip files are generated by the utility in this folder.
|
||||
|
||||
## Example zipper
|
||||
|
||||
The `exampleZipper.js` tool is very similar to the Stackblitz's `builder.js`. The latter creates an HTML file
|
||||
with all the examples' files and the former creates a zip file instead. They both use the `stackblitz.json` file
|
||||
to flag an example as something to stackblitz or zip. For example:
|
||||
The `exampleZipper.js` tool is very similar to the Stackblitz's `builder.js`.
|
||||
The latter creates an HTML file with all the examples' files and the former creates a zip file instead.
|
||||
They both use the `stackblitz.json` file to flag an example as something to stackblitz or zip.
|
||||
For example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -41,8 +42,7 @@ The `exampleZipper.js` won't include any `System.js` related files for CLI-based
|
|||
As mentioned, the tool uses the `stackblitz.json` as a flag and also a configuration file for the zipper.
|
||||
The problem is that not all examples have a stackblitz but they could offer a zip instead.
|
||||
|
||||
In those cases, you can create a `zipper.json` file with the same syntax. It will be ignored by the
|
||||
stackblitz tool.
|
||||
In those cases, you can create a `zipper.json` file with the same syntax. It will be ignored by the stackblitz tool.
|
||||
|
||||
## Executing the zip generation
|
||||
|
||||
|
|
@ -50,5 +50,4 @@ stackblitz tool.
|
|||
|
||||
Where? At `src/generated/zips/`.
|
||||
|
||||
Then the `<live-example>` embedded component will look at this folder to get the zip it needs for
|
||||
the example.
|
||||
Then the `<live-example>` embedded component will look at this folder to get the zip it needs for the example.
|
||||
|
|
|
|||
|
|
@ -1,25 +1,23 @@
|
|||
# Overview
|
||||
|
||||
Many of the documentation pages contain snippets of code examples. Extract these snippets from
|
||||
real working example applications, which are stored in subfolders of the `/aio/content/examples`
|
||||
folder. Each example can be built and run independently. Each example also provides e2e specs, which
|
||||
are run as part of our CircleCI legacy build tasks, to verify that the examples continue to work as
|
||||
expected, as changes are made to the core Angular libraries.
|
||||
Many of the documentation pages contain snippets of code examples.
|
||||
Extract these snippets from real working example applications, which are stored in subfolders of the `/aio/content/examples` folder.
|
||||
Each example can be built and run independently.
|
||||
Each example also provides e2e specs, which are run as part of our CircleCI legacy build tasks, to verify that the examples continue to work as expected, as changes are made to the core Angular libraries.
|
||||
|
||||
In order to build, run and test these examples independently you need to install dependencies into
|
||||
their sub-folder. Also there are a number of common boilerplate files that are needed to configure
|
||||
each example's project. Maintain these common boilerplate files centrally to reduce the amount
|
||||
of effort if one of them needs to change.
|
||||
In order to build, run and test these examples independently you need to install dependencies into their sub-folder.
|
||||
Also there are a number of common boilerplate files that are needed to configure each example's project. Maintain these common boilerplate files centrally to reduce the amount of effort if one of them needs to change.
|
||||
|
||||
> **Note for Windows users**
|
||||
>
|
||||
> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](#symlinked-node_modules) for details). On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator.
|
||||
> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](#symlinked-node_modules) for details).
|
||||
> On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator.
|
||||
|
||||
## Boilerplate overview
|
||||
|
||||
As mentioned, many of the documentation pages contain snippets extracted from real example applications.
|
||||
To achieve that, all those applications needs to contain a basic boilerplate. E.g. a `node_modules`
|
||||
folder, `package.json` with scripts, etc.
|
||||
To achieve that, all those applications needs to contain a basic boilerplate.
|
||||
E.g. a `node_modules` folder, `package.json` with scripts, etc.
|
||||
|
||||
No one wants to maintain the boilerplate on each example, so the goal of this tool is to provide a set of files that works across all the examples.
|
||||
|
||||
|
|
@ -44,7 +42,8 @@ There is also a `common` folder that contains files used in all different exampl
|
|||
### The example-config.json
|
||||
|
||||
Each example is identified by an **example-config.json** configuration file in its root folder.
|
||||
This configuration file indicates what type of boilerplate this example needs. E.g.
|
||||
This configuration file indicates what type of boilerplate this example needs.
|
||||
E.g.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -59,50 +58,47 @@ When the boilerplate tooling runs, it will copy into the example folder all of t
|
|||
<a name="symlinked-node_modules"></a>
|
||||
### A node_modules to share
|
||||
|
||||
With all the boilerplate files in place, the only missing piece are the installed packages. For
|
||||
that you have a `/aio/tools/examples/shared/package.json` which contains **all** the packages
|
||||
needed to run all the examples through all different boilerplates.
|
||||
With all the boilerplate files in place, the only missing piece are the installed packages.
|
||||
For that you have a `/aio/tools/examples/shared/package.json` which contains **all** the packages needed to run all the examples through all different boilerplates.
|
||||
|
||||
After installing these dependencies, a `node_modules/` folder will be created at
|
||||
`/aio/tools/examples/shared/node_modules/`. This folder will be **symlinked** into each example.
|
||||
After installing these dependencies, a `node_modules/` folder will be created at `/aio/tools/examples/shared/node_modules/`.
|
||||
This folder will be **symlinked** into each example.
|
||||
So it is not a copy like the other boilerplate files.
|
||||
|
||||
### End to end tests
|
||||
|
||||
End to end changes between boilerplates.
|
||||
|
||||
For CLI applications, create a `app.e2e-spec.ts` inside the `e2e` folder. The tooling will run
|
||||
`ng e2e` for each CLI based examples.
|
||||
For CLI applications, create a `app.e2e-spec.ts` inside the `e2e` folder.
|
||||
The tooling will run `ng e2e` for each CLI based examples.
|
||||
|
||||
For SystemJS, each example contains an `e2e-spec.ts` file. You can find all the related configuration files
|
||||
in the `/aio/tools/examples/shared` folder.
|
||||
For SystemJS, each example contains an `e2e-spec.ts` file.
|
||||
You can find all the related configuration files in the `/aio/tools/examples/shared` folder.
|
||||
|
||||
### example-boilerplate.js
|
||||
|
||||
This script installs all the dependencies that are shared among all the examples, creates the
|
||||
`node_modules` symlinks and copy all the boilerplate files where needed. It won't do anything
|
||||
about stackblitz nor e2e tests.
|
||||
This script installs all the dependencies that are shared among all the examples, creates the `node_modules` symlinks and copy all the boilerplate files where needed.
|
||||
It won't do anything about stackblitz nor e2e tests.
|
||||
|
||||
It also contains a function to remove all the boilerplate. It uses a `git clean -xdf` to do
|
||||
the job. It will remove all files that don't exist in the git repository, **including any
|
||||
new file that you are working on that hasn't been stage yet.** So be sure to save your work
|
||||
before removing the boilerplate.
|
||||
It also contains a function to remove all the boilerplate.
|
||||
It uses a `git clean -xdf` to do the job.
|
||||
It will remove all files that don't exist in the git repository, **including any new file that you are working on that hasn't been stage yet.**
|
||||
So be sure to save your work before removing the boilerplate.
|
||||
|
||||
### run-example-e2e.js
|
||||
|
||||
This script will find all the `e2e-spec.ts` files and run them.
|
||||
|
||||
To not run all tests, you can use the `--filter=name` flag to run the example's e2e that contains
|
||||
that name.
|
||||
To not run all tests, you can use the `--filter=name` flag to run the example's e2e that contains that name.
|
||||
|
||||
It also has an optional `--setup` flag to run the `example-boilerplate.js` script and install
|
||||
the latest `webdriver`.
|
||||
It also has an optional `--setup` flag to run the `example-boilerplate.js` script and install the latest `webdriver`.
|
||||
|
||||
It will create a `/aio/protractor-results.txt` file when it finishes running tests.
|
||||
|
||||
### Updating example dependencies
|
||||
|
||||
With every major release, we update the examples to be on the latest version. The following steps to update are:
|
||||
With every major release, we update the examples to be on the latest version.
|
||||
The following steps to update are:
|
||||
|
||||
* In the `shared/package.json` file, bump all the `@angular/*`, `@angular-devkit/*`, `rxjs`, `typescript`, and `zone.js` package versions to the version that corresponds with the [framework version](../../../package.json).
|
||||
* In the `shared` folder, run `yarn` to update the dependencies for the shared `node_modules` and the `yarn.lock` file.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
# How to update the CLI project
|
||||
|
||||
The Angular CLI default setup is updated using `ng update`. Any necessary file changes will be done automatically through migration schematics.
|
||||
The Angular CLI default setup is updated using `ng update`.
|
||||
Any necessary file changes will be done automatically through migration schematics.
|
||||
|
||||
In the `cli` folder, update the Angular CLI depedencies to the latest version:
|
||||
|
||||
|
|
@ -18,7 +19,8 @@ Commit any changes to the `cli` folder to the repository.
|
|||
|
||||
## Updating other CLI-based projects
|
||||
|
||||
Along with the boilerplate files for the `cli` folder, the other cli-based projects need to be updated also. Each cli-based project has slightly modified files specific to the project type. Make sure any necessary changes to these projects are made also to be in alignment with the `cli` project files.
|
||||
Along with the boilerplate files for the `cli` folder, the other cli-based projects need to be updated also. Each cli-based project has slightly modified files specific to the project type.
|
||||
Make sure any necessary changes to these projects are made also to be in alignment with the `cli` project files.
|
||||
|
||||
The specific changes to each project type are listed below:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Overview
|
||||
|
||||
[Stackblitz](https://stackblitz.com/) is an online tool for creating, collaborating and sharing ideas.
|
||||
[Stackblitz](https://stackblitz.com/) is an online tool for creating, collaborating and sharing ideas.
|
||||
In AIO we use it to share one or more runnable versions of our examples.
|
||||
|
||||
Stackblitz can be used both on a separate page and in an embedded form.
|
||||
|
|
@ -8,24 +8,25 @@ Stackblitz can be used both on a separate page and in an embedded form.
|
|||
|
||||
## Stackblitz generation
|
||||
|
||||
Both forms are created within `builder.js`. How is a stackblitz created? What is the process from a
|
||||
directory with files to a link with a stackblitz.
|
||||
Both forms are created within `builder.js`.
|
||||
How is a stackblitz created?
|
||||
What is the process from a directory with files to a link with a stackblitz.
|
||||
|
||||
An "executable" stackblitz is an HTML file with a `<form>` that makes a post to stackblitz on submit. It
|
||||
contains an `<input>` element for each file we need in the stackblitz.
|
||||
An "executable" stackblitz is an HTML file with a `<form>` that makes a post to stackblitz on submit.
|
||||
It contains an `<input>` element for each file we need in the stackblitz.
|
||||
|
||||
The form will be submitted on load, so you can either double click the HTML file or open it with an
|
||||
anchor tag to open the stackblitz.
|
||||
The form will be submitted on load, so you can either double click the HTML file or open it with an anchor tag to open the stackblitz.
|
||||
|
||||
So the `builder.js` job is to get all the needed files from an example and build this HTML file for you.
|
||||
|
||||
## Customizing the generation per example basis
|
||||
|
||||
How does this tool know what is an example and what is not? It will look for all folders containing a
|
||||
`stackblitz.json` file. If found, all files within the folder and subfolders will be used in the stackblitz, with
|
||||
a few generic exceptions that you can find at `builder.js`.
|
||||
How does this tool know what is an example and what is not?
|
||||
It will look for all folders containing a `stackblitz.json` file.
|
||||
If found, all files within the folder and subfolders will be used in the stackblitz, with a few generic exceptions that you can find at `builder.js`.
|
||||
|
||||
You can use the `stackblitz.json` to customize the stackblitz generation. For example:
|
||||
You can use the `stackblitz.json` to customize the stackblitz generation.
|
||||
For example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -39,21 +40,21 @@ You can use the `stackblitz.json` to customize the stackblitz generation. For ex
|
|||
}
|
||||
```
|
||||
|
||||
Here you can specify a description for the stackblitz, some tags and also a files array where you
|
||||
can specify extra files to add or to ignore.
|
||||
Here you can specify a description for the stackblitz, some tags and also a files array where you can specify extra files to add or to ignore.
|
||||
|
||||
## Executing the stackblitz generation
|
||||
|
||||
`generateStackblitz.js` will create a stackblitz for each `stackblitz.json` it finds.
|
||||
|
||||
Where? At `src/generated/live-examples/`.
|
||||
Where?
|
||||
At `src/generated/live-examples/`.
|
||||
|
||||
Then the `<live-example>` embedded component will look at this folder to get the stackblitz it needs for the
|
||||
example.
|
||||
|
||||
## Appendix: Why not generating stackblitz at runtime?
|
||||
|
||||
At AngularJS, all the plunker examples were generated at runtime. The downside was that all the example code had to be
|
||||
deployed as well and would no longer be useful after the plunker was generated.
|
||||
At AngularJS, all the plunker examples were generated at runtime.
|
||||
The downside was that all the example code had to be deployed as well and would no longer be useful after the plunker was generated.
|
||||
|
||||
This `StackblitzBuilder` tool takes a few seconds to run, and the end result is only 3mb~.
|
||||
|
|
|
|||
|
|
@ -1,36 +1,27 @@
|
|||
# Overview
|
||||
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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 this folder (`aio/tools/transforms`).
|
||||
|
||||
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).
|
||||
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`.
|
||||
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`.
|
||||
|
||||
* 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.
|
||||
* 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.
|
||||
|
||||
## Other packages
|
||||
|
||||
|
|
@ -46,5 +37,5 @@ you are working on.
|
|||
|
||||
## Templates
|
||||
|
||||
All the templates for the angular.io dgeni transformations are stoted in the `tools/transforms/templates`
|
||||
folder. See the [README](./templates/README.md).
|
||||
All the templates for the angular.io dgeni transformations are stoted in the `tools/transforms/templates` folder.
|
||||
See the [README](./templates/README.md).
|
||||
|
|
|
|||
Loading…
Reference in New Issue