honeymoose/angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update README and author guide about doc build errors (#19276)

Browse Source 
- 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
This commit is contained in:
Ward Bell 2017-09-19 11:54:49 -07:00 committed by Igor Minar
parent 580372f23d
commit a5ee653da0
2 changed files with 27 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
aio/README.md
View File

@ -52,7 +52,7 @@ For more details see #16745.
## Guide to authoring ## 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**: descriptions of the modules, classes, interfaces, decorators, etc that make up the Angular platform.
API docs are generated directly from the source code. API docs are generated directly from the source code.
@ -107,8 +107,16 @@ yarn start
yarn docs-watch 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. * 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 * 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. 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).

17
aio/content/guide/docs-style-guide.md
View File

@ -360,6 +360,23 @@ located in the `content/examples/docs-style-guide` directory.
</div> </div>
<div class="alert is-important">
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:
<code-example title="content/examples/.gitignore">
# my-guide
!my-guide/src/something.js
!my-guide/more-javascript*.js
</code-example>
</div>
#### Code-example attributes #### Code-example attributes
You control the _code-example_ output by setting one or more of its attributes: You control the _code-example_ output by setting one or more of its attributes: