From a5ee653da0f23bc96ac36553a1e335e0f7da137a Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Tue, 19 Sep 2017 11:54:49 -0700 Subject: [PATCH] docs: update README and author guide about doc build errors (#19276) - tells reader about `yarn serve-and-sync`. - directs reader to look to docs-style-guide if get doc build error. - update docs-style-guide to warn about ignored code files. PR Close #19276 --- aio/README.md | 10 +++++++++- aio/content/guide/docs-style-guide.md | 19 ++++++++++++++++++- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/aio/README.md b/aio/README.md index 330540c559..dd2c51ab13 100644 --- a/aio/README.md +++ b/aio/README.md @@ -52,7 +52,7 @@ For more details see #16745. ## Guide to authoring -There are two types of content in the documentatation: +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. @@ -107,8 +107,16 @@ yarn start 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. + +* 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 diff --git a/aio/content/guide/docs-style-guide.md b/aio/content/guide/docs-style-guide.md index 8c1b629dca..400a2ba5d7 100644 --- a/aio/content/guide/docs-style-guide.md +++ b/aio/content/guide/docs-style-guide.md @@ -348,7 +348,7 @@ Here's the brief markup that produced that lengthy snippet: ``` You identified the snippet's source file by setting the `path` attribute to sample folder's location _within_ `content/examples`. -In this example, that path is `docs-style-guide/src/app/app.module.ts`. +In this example, that path is `docs-style-guide/src/app/app.module.ts`. You added a header to tell the reader where to find the file by setting the `title` attribute. Following convention, you set the `title` attribute to the file's location within the sample's root folder. @@ -360,6 +360,23 @@ located in the `content/examples/docs-style-guide` directory. +
+ +The doc tooling reports an error if the file identified in the path does not exist **or is _git_-ignored**. + +Most `.js` files are _git_-ignored. +If you want to include an ignored code file in your project and display it in a guide you must _un-ignore_ it. + +The preferred way to un-ignore a file is to update the `content/examples/.gitignore` like this: + + + # my-guide + !my-guide/src/something.js + !my-guide/more-javascript*.js + + +
+ #### Code-example attributes You control the _code-example_ output by setting one or more of its attributes: