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

docs(aio): change to overall prose

This commit is contained in:
Shefali Sinha 2017-06-14 14:39:15 -07:00 committed by Hans
parent fd6c4e371b
commit b1dab181e0
1 changed files with 112 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -19,15 +19,15 @@ You will use the following layouts throughout your documentation to specify sect
## Main Section Title ## Main Section Title
Main section titles should preceeded by ##. This is equvalent to the h2 HTML tag. Content can start on the next line. Main section titles should preceeded by ##. This is equvalent to the h2 HTML tag. Content for this section can start on the next line.
## Sub Section Title ## Sub Section Title
The content in any sub-section is related to the main section content and _falls within_ the main section. Any sub-section title should preceeded by ###. This is equivalent to the h3 HTML tag. Content can start on the next line. The content in any sub-section is related to the main section and _falls within_ the main section. Any sub-section title should preceeded by ###. This is equivalent to the h3 HTML tag. Content for this sub-section can start on the next line.
## Additional Sub Section Information ### Additional Sub Section Information
To present information to the user that may require redirection to other pages, internal or external to the docs, you can use class 'l-sub-section'. Here is an example of such a sub-section. To present more detailed information to the user that may require redirection to other pages, internal or external to the docs, you can use class 'l-sub-section'. Here is an example of such a sub-section.
<div class="l-sub-section"> <div class="l-sub-section">
@ -49,38 +49,38 @@ The code for this is here.
</div> </div>
``` ```
Note that blank lines have been left within the div tags. Blank lines within HTML tags is a cue to Markdown to process the tags and the content within these tags as HTML.
## Table of Contents ## Table of Contents
The table of contents (TOC) is automatically generated by looking at section titles and sub-section titles. By default the TOC is two levels deep, that is, it displays only the section and sub-section titles. The table of contents (TOC) is automatically generated by fetching section titles and sub-section titles. By default the TOC is two levels deep, that is, it is limited to displaying only the section and sub-section titles.
To exclude a section or sub-section title from the TOC, use a class called 'no-toc'. This class must be used in conjunction with HTML heading tags. Titles displayed using Markdown heading hash tags cannot be excluded. To exclude a section or sub-section title from the TOC, use a class called 'no-toc'. This class must be used in conjunction with HTML heading tags. Titles displayed using Markdown heading hash tags cannot be excluded from the TOC.
### Example ### Example
```html ```html
<h3 class="no-toc"> <h3 class="no-toc">
Not for our TOC Heading not displated in the TOC
</h3> </h3>
``` ```
## Left-hand Side Navigation ## Left-hand Side Navigation
When you create the Markdown file for your guide, and include it at the appropriate location in navigation.json, you should see the title of your guide displayed in the navigation panel on the left hand side of the docs. You can make further modifications to navigation.json to include any sub-chapters you may have. When you create the Markdown file for your guide, and include it at the appropriate location in navigation.json, you should see the title of your guide displayed in the navigation panel on the left hand side of the docs. You can make further modifications to navigation.json to include any sub-chapters you may have. The sub-chapter titles should be displayed in the navigation panel, indented below the title of the main chapter.
## Code Examples ## Code Examples
Code examples cn be used to provide code listings. This code can be displayed inline or pulled from files. Code examples allow you to display code with line numbers, from various programming languages, display in tabbed interfaces and such. Below are a few examples of how you can add/customize code examples in a page. Code examples can be used to display code on a page. This code can be displayed inline or displaying by extracting from files. Code examples allow you to display code with line numbers, code of various programming languages, display these in tabbed interfaces and such.
### Code-Example Attributes ### Code-Example Attributes
* path: a file in the content/examples folder * path: a file in the content/examples folder
* title: seen in the header * title: seen in the header of the code listing
* region: name of a docregion * region: name of a docregion, a merked region in a source file and explained in a section later in this guide
* language: specify only for inline examples. Values can be javascript, html, css, typescript, json, sh or any other language that you will use in your Angular application. * language: specify only for inline examples. Values can be javascript, html, css, typescript, json, sh or any other language that you will use in your Angular application
* linenums: true, false, for example linenums:4 to speficy that the starting line is 4. When not specified, line numbers are displayed when there are 10 or more lines of code * linenums: true, false, for example linenums=4 to specify that the starting line is 4. When not specified, line numbers are automatically displayed when there are 10 or more lines of code
* format: nocode, linenums??
* class: no-box, code-shell, avoid * class: no-box, code-shell, avoid
### Including a code example from the _examples_ folder ### Including a code example from the _examples_ folder
@ -104,20 +104,30 @@ Code-example displays code or content exactly as entered in a code-example.
</code-example> </code-example>
``` ```
#### Example: #### Code from an External File
Code-example will read the content/examples/toh-pt1/src/index.html file and include it with the heading 'src/index.html'. Note that the file will be properly escaped and color coded according to the extension on the file (html in this case). The code will be displayed as shown here.
<code-example path="toh-pt1/src/index.html" linenums="true" title="src/index.html"></code-example> <code-example path="toh-pt1/src/index.html" linenums="true" title="src/index.html"></code-example>
The code will read the content/examples/toh-pt1/src/index.html file and include it with the heading 'src/index.html'. Note that the file will be properly escaped and color coded according to the extension on the file (html in this case).
The code for the above example is displayed below.
```html ```html
<code-example path="toh-pt1/src/index.html" linenums="true" title="src/index.html"> <code-example path="toh-pt1/src/index.html" linenums="true" title="src/index.html">
</code-example> </code-example>
``` ```
#### Example of a command to be entered in a command window #### Commands in a Command Window
To display commands in a command window, you can use the code-shell class supported by code-examples.
<code-example language="sh" class="code-shell"> <code-example language="sh" class="code-shell">
npm start npm start
</code-example> </code-example>
The code below uses the code-shell class to display the command terminal and code within the terminal.
```html ```html
<code-example language="sh" class="code-shell"> <code-example language="sh" class="code-shell">
npm start npm start
@ -125,7 +135,10 @@ The code will read the content/examples/toh-pt1/src/index.html file and include
``` ```
#### Example of code to be avoided #### Example of Code to be Avoided
To present code that users should avoid, you can use a class called avoid.
<code-example class="avoid" title="hero-details.component.ts (Avoid)"> <code-example class="avoid" title="hero-details.component.ts (Avoid)">
&lt;hero-details <em>nghost-pmm-5&gt; &lt;hero-details <em>nghost-pmm-5&gt;
&lt;h2 </em>ngcontent-pmm-5&gt;Mister Fantastic&lt;/h2&gt; &lt;h2 </em>ngcontent-pmm-5&gt;Mister Fantastic&lt;/h2&gt;
@ -134,6 +147,9 @@ The code will read the content/examples/toh-pt1/src/index.html file and include
&lt;/hero-team&gt; &lt;/hero-team&gt;
&lt;/hero-details&gt; &lt;/hero-details&gt;
</code-example> </code-example>
The code to create this display is below.
```html ```html
<code-example class="avoid" title="hero-details.component.ts (Avoid)"> <code-example class="avoid" title="hero-details.component.ts (Avoid)">
<hero-details <em>nghost-pmm-5> <hero-details <em>nghost-pmm-5>
@ -146,7 +162,7 @@ The code will read the content/examples/toh-pt1/src/index.html file and include
``` ```
#### Example of an HTML backticked code block #### Example of HTML code
Backticked code blocks can be used to enclose HTML code without using escape characters. Backticked code blocks can be used to enclose HTML code without using escape characters.
@ -158,6 +174,8 @@ Backticked code blocks can be used to enclose HTML code without using escape cha
</hero-team> </hero-team>
</hero-details> </hero-details>
``` ```
You can use the syntax below to enclose HTML within a backticked code block.
<code-example language="html"> <code-example language="html">
```html ```html
&lt;hero-details&gt; &lt;hero-details&gt;
@ -169,50 +187,7 @@ Backticked code blocks can be used to enclose HTML code without using escape cha
``` ```
</code-example> </code-example>
There is Code-tabs and Code-pane that provides the same service but for multiple examples within a tabbed interface. #### Marking up a Source File
### Code-tabs Attributes
* linenums: display line numbers in the code in all tabs
### Code-pane Attributes
* path: a file in the content/examples folder
* title: seen in the header
* linenums: display line numbers in the code in this tab
#### Example:
This example uses the source code for a small application that bundles with Webpack techniques. This will create three tabs, each with its own title and appropriately color coded. By default, line numbers are shown. Line number display can be specified using the linenums attribute at the code tab or code pane level. The example below shows us how to display line numbers in just one code pane.
<code-tabs>
<code-pane title="src/index.html" path="webpack/src/index.html">
</code-pane>
<code-pane title="src/tsconfig.json" path="webpack/src/tsconfig.1.json">
</code-pane>
<code-pane title="src/main.ts" path="webpack/src/main.ts">
</code-pane>
<code-pane title="src/assets/css/styles.css" path="webpack/src/assets/css/styles.css">
</code-pane>
</code-tabs>
The code below will create multiple tabs, each with its own title and appropriately color coded.
```html
<code-tabs linenums="false">
<code-pane title="src/index.html" path="webpack/src/index.html">
</code-pane>
<code-pane title="src/tsconfig.json" path="webpack/src/tsconfig.json" linenums="true">
</code-pane>
<code-pane title="src/main.ts" path="webpack/src/main.ts" linenums="true">
</code-pane>
<code-pane title="src/assets/css/styles.css" path="webpack/src/assets/css/styles.css">
</code-pane>
</code-tabs>
```
### Marking up an example file for use by code-example
To mark any part of a file, add a single comment line in the line above the area to be marked. The comment should contain the string #docregion. Optionally, a second string can follow. The second string is the 'name' of the region. A file may have any number of #docregion comments with the only requirement being that the names of each region within a single file be unique. This also means that there can only be one blank docregion. Further, docregions can be nested. To mark any part of a file, add a single comment line in the line above the area to be marked. The comment should contain the string #docregion. Optionally, a second string can follow. The second string is the 'name' of the region. A file may have any number of #docregion comments with the only requirement being that the names of each region within a single file be unique. This also means that there can only be one blank docregion. Further, docregions can be nested.
@ -247,7 +222,9 @@ export class AppComponent {
&lt;/code-example&gt; &lt;/code-example&gt;
</code-example> </code-example>
<code-example path="docs-style-guide/app.component.ts" linenums="false" title="a docregion" region="selected-hero"> Here is code for the above code-examples that use docregions.
<code-example path="docs-style-guide/app.component.ts" linenums="false" title="A docregion" region="selected-hero">
</code-example> </code-example>
<code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters"> <code-example path="docs-style-guide/app.component.ts" linenums="false" title="Multiple docregions" region="onSelect-parameters">
@ -271,46 +248,85 @@ as can CSS files:
``` ```
### Inline code and code examples provided directly i.e. not from an example file. ## Code Tabs
Code can be included directly inline, that is, not be fetched from some external file. Code tabs display code much like Code examples do. The added advantage is that they can display mutiple code samples within a tabbed interface. Each tab is displayed using Code-pane.
### Code-tabs Attributes
* linenums: true, false, display line numbers in the code in all tabs when the number of code statements are 10 or more
### Code-pane Attributes
* path: a file in the content/examples folder
* title: seen in the header of a tab
* linenums: true, false, display line numbers for the code in this tab when the number of code statements are 10 or more
The example below uses the source code for a small application that bundles with Webpack techniques. This will create multiple tabs, each with its own title and be appropriately color coded. By default, line numbers are shown. Line number display can be specified using the linenums attribute at the code tab or code pane level. The example below shows us how to display line numbers in just one code pane.
<code-tabs>
<code-pane title="src/index.html" path="webpack/src/index.html">
</code-pane>
<code-pane title="src/tsconfig.json" path="webpack/src/tsconfig.1.json" linenums="false">
</code-pane>
<code-pane title="src/main.ts" path="webpack/src/main.ts">
</code-pane>
<code-pane title="src/assets/css/styles.css" path="webpack/src/assets/css/styles.css">
</code-pane>
</code-tabs>
The code below will create multiple tabs, each with its own title and be appropriately color coded.
#### Example
```html ```html
code-example(format="linenums" language="javascript"). <code-tabs linenums="false">
//SOME CODE <code-pane title="src/index.html" path="webpack/src/index.html">
``` </code-pane>
<code-pane title="src/tsconfig.json" path="webpack/src/tsconfig.json" linenums="false">
#### Specify starting line number </code-pane>
```html <code-pane title="src/main.ts" path="webpack/src/main.ts">
code-example(language="html" format="linenums:4") </code-pane>
var title = "This starts on line four"; <code-pane title="src/assets/css/styles.css" path="webpack/src/assets/css/styles.css">
</code-pane>
</code-tabs>
``` ```
{@a section-LiveExamples} {@a section-LiveExamples}
## Live Examples ## Live Examples
Here is how we do live examples. All examples here will point to TOH-6 for convenience. Here is how we do live examples. All examples here will point to other guides such as TOH-6 for convenience.
### Plain Live Example ### Plain Live Example
When a live example is included in a guide, it allows readers to run the example and download the code that the Author has placed in the content/examples folder for their respective guide. A plain live example looks like this: <live-example name="toh-pt6"></live-example>
The code is shown here.
```html ```html
<live-example></live-example> <live-example></live-example>
``` ```
A plain live example looks like this: <live-example name="toh-pt6"></live-example>
### Live Example with Title Attribute ### Live Example with Title Attribute
To replace 'live-example' with a title, you can provide a title as shown here.
```html ```html
<live-example title="Live Example with User Desired Title"></live-example> <live-example title="Live Example with User Desired Title"></live-example>
``` ```
### Live Example with Body like seen in router, same exact result as attrib title ### Live Example with Body
Another way to display aletrnative text for 'live-example' is to include it in the body of the live-example. The effect is the same as when you use the title attribute.
```html ```html
<live-example>Live Example Flesh & Blood</live-example> <live-example>Live Example Flesh & Blood</live-example>
``` ```
### Live Example from Another Guide ### Live Example from Another Guide
Example of live-example from the router guide <live-example name="router">Live Example from the Router guide</live-example>.
```html ```html
<live-example name="router">Live Example from the Router guide</live-example> <live-example name="router">Live Example from the Router guide</live-example>
``` ```
@ -331,7 +347,7 @@ A plain live example looks like this: <live-example name="toh-pt6"></live-exampl
``` ```
### Live Example with Embedded Plunkers ### Live Example with Embedded Plunkers
Embedded Plunkrs have default image. img allows you to override the deafult image. Embedded Plunkrs have default image. img allows you to override the default image.
```html ```html
<live-example embedded img="guide/router/img1.png"></live-example> <live-example embedded img="guide/router/img1.png"></live-example>
``` ```
@ -339,28 +355,22 @@ Embedded Plunkrs have default image. img allows you to override the deafult ima
{@a section-Anchors} {@a section-Anchors}
## Anchors ## Anchors
To mark a location that a reader should reach when they click on an anchor, insert the tag below at that location. To mark a location that a reader should reach when they click an anchor link, insert the anchor tag shown below at that location.
<code-example language="html"> <code-example language="html">
I have been marked using {@ section-Anchors} `{@a section-Anchors}` My location has been marked using {@ section-Anchors}
</code-example> </code-example>
To use this anchor, replace alternative text below with text that will be visible to the reader and that the reader will click on. Replace path-to-page with the relative path to the page that has the location that the reader should reach. To use this anchor, replace alternative text below with text that will be visible to the reader and that the reader will click on. Replace path-to-page/dir-of-page with the relative path to the page that has the location that the reader should reach.
```html ```html
[alternative text] (path-to-page/dir-of-page/#section-Anchors) [alternative text] (path-to-page/dir-of-page/#section-Anchors)
``` ```
### Example
[Click this] (guide/docs-style-guide/#section-Anchors) to reach the beginning of this section on Anchors.
## Alerts ## Alerts
Please use alerts sparingly throughout the docs. They are meant to draw attention to important occasions. Alerts should not be used for multi-line content (use callouts insteads) or stacked on top of each other. Please use alerts sparingly throughout the docs. They are meant to draw attention to important occasions. Alerts should not be used for multi-line content (use callouts insteads) or stacked on top of each other. Note that the content of an alert is indented to the right by two spaces.
<div class="l-sub-section"> <div class="l-sub-section">
### Adding an Alert
<div class="alert is-critical"> <div class="alert is-critical">
A very critical alert. A very critical alert.
</div> </div>
@ -393,7 +403,7 @@ A very helpful alert.
## Callouts ## Callouts
Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention on important occasions. Unlike alerts, callouts are designed to display multi-line content. Please use callouts sparingly throughout the docs. Callouts (like alerts) are meant to draw attention to important occasions. Unlike alerts, callouts are designed to display multi-line content.
<div class="l-sub-section"> <div class="l-sub-section">
@ -443,7 +453,6 @@ Pitchfork hoodie semiotics, roof party pop-up paleo messenger bag cred Carles to
``` ```
## Trees ## Trees
Trees can be used to represent heirarchial data. Here is an example. Trees can be used to represent heirarchial data. Here is an example.
@ -500,7 +509,7 @@ Trees can be used to represent heirarchial data. Here is an example.
</div> </div>
Here is the code for this tree Here is the code for this tree.
```html ```html
<div class='filetree'> <div class='filetree'>
@ -545,9 +554,6 @@ Here is the code for this tree
Tables can be used to present tabular data as it relates to each other. Tables can be used to present tabular data as it relates to each other.
<div class="l-sub-section">
### Adding a Table
<style> <style>
td, th {vertical-align: top} td, th {vertical-align: top}
@ -622,7 +628,7 @@ Tables can be used to present tabular data as it relates to each other.
</table> </table>
To-do: format below closer to what is seen in old guide Here is code for this table.
```html ```html
table table
@ -634,10 +640,12 @@ table
td AngularJS td AngularJS
td Routing td Routing
td fast td fast
tr
td Angular 2
td Routing
td faster
``` ```
</div>
## Images ## Images
### Using Images ### Using Images