diff --git a/aio/README.md b/aio/README.md index bf2e18a827..1370345551 100644 --- a/aio/README.md +++ b/aio/README.md @@ -30,26 +30,26 @@ Here are the most important tasks you might need to use: * `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 `-- --local` to use your local version of Angular contained in the "dist" folder. +* `yarn boilerplate:add` - generate all the boilerplate code for the examples, so that they can be run locally. Add the option `--local` to use your local version of Angular contained in the "dist" folder. * `yarn boilerplate:remove` - remove all the boilerplate code that was added via `yarn boilerplate:add`. * `yarn generate-plunkers` - generate the plunker 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 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 -Since abb36e3cb, running `yarn start -- --prod` will no longer set up the ServiceWorker, which +Since abb36e3cb, running `yarn start --prod` will no longer set up the ServiceWorker, which would require manually running `yarn sw-manifest` and `yarn sw-copy` (something that is not possible with webpack serving the files from memory). If you want to test ServiceWorker locally, you can use `yarn build` and serve the files in `dist/` -with `yarn http-server -- dist -p 4200`. +with `yarn http-server dist -p 4200`. For more details see #16745. @@ -117,10 +117,10 @@ 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. +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. * If you get a build error complaining about examples or any other odd behavior, be sure to consult -the [Authors Style Guide](https://angular.io/guide/docs-style-guide). \ No newline at end of file +the [Authors Style Guide](https://angular.io/guide/docs-style-guide). diff --git a/aio/content/guide/docs-style-guide.md b/aio/content/guide/docs-style-guide.md index 400a2ba5d7..2006ef8ae3 100644 --- a/aio/content/guide/docs-style-guide.md +++ b/aio/content/guide/docs-style-guide.md @@ -2,13 +2,13 @@ This page presents design and layout guidelines for Angular documentation pages. These guidelines should be followed by all guide page authors. Deviations must be approved by the documentation editor. -Most guide pages should have [accompanying sample code](#from-code-samples) with -[special markup](#source-code-markup) for the code snippets on the page. -Code samples should adhere to the -[style guide for Angular applications](guide/styleguide "Application Code Style Guide") +Most guide pages should have [accompanying sample code](#from-code-samples) with +[special markup](#source-code-markup) for the code snippets on the page. +Code samples should adhere to the +[style guide for Angular applications](guide/styleguide "Application Code Style Guide") because readers expect consistency. -For clarity and precision, every guideline on _this_ page is illustrated with a working example, +For clarity and precision, every guideline on _this_ page is illustrated with a working example, followed by the page markup for that example ... as shown here. ```html @@ -19,13 +19,13 @@ followed by the page markup for that example ... as shown here. To make changes to the documentation pages and sample code, clone the [Angular github repository](https://github.com/angular/angular "Angular repo") and go to the `aio/` folder. -The [aio/README.md](https://github.com/angular/angular/blob/master/aio/README.md "AIO ReadMe") explains how to install and use the tools to edit and test your changes. +The [aio/README.md](https://github.com/angular/angular/blob/master/aio/README.md "AIO ReadMe") explains how to install and use the tools to edit and test your changes. Here are a few essential commands for guide page authors. 1. `yarn setup` — installs packages; builds docs, plunkers, and zips. -1. `yarn docs-watch -- --watch-only` — watches for saved content changes and refreshes the browser. The (optional) `--watch-only` flag skips the initial docs rebuild. +1. `yarn docs-watch --watch-only` — watches for saved content changes and refreshes the browser. The (optional) `--watch-only` flag skips the initial docs rebuild. 1. `yarn start` — starts the doc viewer application so you can see your local changes in the browser. @@ -33,9 +33,9 @@ Here are a few essential commands for guide page authors. ## Guide pages - All but a few guide pages are [markdown](https://daringfireball.net/projects/markdown/syntax "markdown") files with an `.md` extension. + All but a few guide pages are [markdown](https://daringfireball.net/projects/markdown/syntax "markdown") files with an `.md` extension. -Every guide page file is stored in the `content/guide` directory. Although the [side navigation](#navigation) panel displays as a hierarchy, the directory is flat with no sub-folders. +Every guide page file is stored in the `content/guide` directory. Although the [side navigation](#navigation) panel displays as a hierarchy, the directory is flat with no sub-folders. The flat folder approach allows us to shuffle the apparent navigation structure without moving page files or redirecting old page URLs. The doc generation process consumes the markdown files in the `content/guide` directory and produces JSON files in the `src/generated/docs/guide` directory, which is also flat. Those JSON files contain a combination of document metadata and HTML content. @@ -52,7 +52,7 @@ _Tutorial_ pages are exactly like guide pages. The only difference is that they _API_ pages are generated from Angular source code into the `src/generated/docs/api` directory. The doc viewer translates URLs that begin `api/` into requests for document JSON files in that directory. This style guide does not discuss creation or maintenance of API pages. -_Marketing_ pages are similar to guide pages. They're located in the `content/marketing` directory. While they can be markdown files, they may be static HTML pages or dynamic HTML pages that render with JSON data. +_Marketing_ pages are similar to guide pages. They're located in the `content/marketing` directory. While they can be markdown files, they may be static HTML pages or dynamic HTML pages that render with JSON data. Only a few people are authorized to write marketing pages. This style guide does not discuss creation or maintenance of marketing pages. @@ -70,14 +70,14 @@ Standard markdown processors don't allow you to put markdown _within_ HTML tags.