cargdev/angular
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs-infra): always default to no linenums in <aio-code> (#31674)

Browse Source 
Previously, `linenums` defaulted to true if the content was more than 10
lines long and false otherwise.

Since in most cases linenums add unnecessary visual noise, this commit
changes `linenums` to always default to false (regardless of the size of
the content). It can be still be turned on by explicitly setting to true
or a number.

PR Close #31674
This commit is contained in:
George Kalpakas
2019-07-20 20:31:30 +03:00
committed by Miško Hevery
parent 3d7303efc0
commit dd0be7feb7
4 changed files with 47 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -428,7 +428,7 @@ You control the _code-example_ output by setting one or more of its attributes:
* `region`- displays the source file fragment with that region name; regions are identified by _docregion_ markup in the source file, as explained [below](#region "Displaying a code fragment").
* `linenums`- value may be `true`, `false`, or a `number`. When not specified, line numbers are automatically displayed when there are greater than 10 lines of code. The rarely used `number` option starts line numbering at the given value. `linenums=4` sets the starting line number to 4.
* `linenums`- value may be `true`, `false`, or a `number`. When not specified, line numbers default to `false` (i.e. no line numbers are displayed). The rarely used `number` option starts line numbering at the given value. `linenums=4` sets the starting line number to 4.
* `class`- code snippets can be styled with the CSS classes `no-box`, `code-shell`, and `avoid`.
@ -465,8 +465,6 @@ A couple of observations:
1. Omitting the `header` is fine when the source of the fragment is obvious. We just said that this is a fragment of the `app.module.ts` file which was displayed immediately above, in full, with a header.
There's no need to repeat the header.
1. The line numbers disappeared. By default, the doc viewer omits line numbers when there are fewer than 10 lines of code; it adds line numbers after that. You can turn line numbers on or off explicitly by setting the `linenums` attribute.
#### Example of bad code
Sometimes you want to display an example of bad code or bad design.
@ -496,18 +494,18 @@ Code tabs display code much like _code examples_ do. The added advantage is tha
#### Code-tabs attributes
* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when code for a tab pane has greater than 10 lines of code.
* `linenums`: The value can be `true`, `false` or a number indicating the starting line number. If not specified, it defaults to `false`.
#### Code-pane attributes
* `path` - a file in the content/examples folder
* `header` - seen in the header of a tab
* `linenums` - overrides the `linenums` property at the `code-tabs` level for this particular pane. The value can be `true`, `false` or a number indicating the starting line number. If not specified, line numbers are enabled only when the number of lines of code are greater than 10.
* `linenums` - overrides the `linenums` property at the `code-tabs` level for this particular pane. The value can be `true`, `false` or a number indicating the starting line number. If not specified, it defaults to `false`.
The next example displays multiple code tabs, each with its own header.
It demonstrates control over display of line numbers at both the `<code-tabs>` and `<code-pane>` levels.
<code-tabs linenums="false">
<code-tabs linenums="true">
<code-pane
header="app.component.html"
path="docs-style-guide/src/app/app.component.html">
@ -515,7 +513,7 @@ It demonstrates control over display of line numbers at both the `<code-tabs>` a
<code-pane
header="app.component.ts"
path="docs-style-guide/src/app/app.component.ts"
linenums="true">
linenums="false">
</code-pane>
<code-pane
header="app.component.css (heroes)"
@ -530,11 +528,11 @@ It demonstrates control over display of line numbers at both the `<code-tabs>` a
Here's the markup for that example.
Note how the `linenums` attribute in the `<code-tabs>` explicitly disables numbering for all panes.
The `linenums` attribute in the second pane restores line numbering for _itself only_.
Note how the `linenums` attribute in the `<code-tabs>` explicitly enables numbering for all panes.
The `linenums` attribute in the second pane disables line numbering for _itself only_.
```html
<code-tabs linenums="false">
<code-tabs linenums="true">
<code-pane
header="app.component.html"
path="docs-style-guide/src/app/app.component.html">
@ -542,7 +540,7 @@ The `linenums` attribute in the second pane restores line numbering for _itself
<code-pane
header="app.component.ts"
path="docs-style-guide/src/app/app.component.ts"
linenums="true">
linenums="false">
</code-pane>
<code-pane
header="app.component.css (heroes)"

10
aio/content/marketing/test.html
View File

@ -3,7 +3,7 @@
<h2>&lt;code-tabs&gt;</h2>
<p>No linenums at code-tabs level</p>
<code-tabs >
<code-tabs>
<code-pane header='TS code file' language='ts'>
class {
foo(param: string) {}
@ -26,7 +26,7 @@
</code-tabs>
<p></p>
<p>No linenums at code-tabs level; linenums=true for HTML pane</p>
<p>No linenums at code-tabs level; linenums=true for second HTML pane</p>
<code-tabs >
<code-pane header='TS code file' language='ts'>
class {
@ -43,8 +43,8 @@
<p>One line.</p>
<code-example>const foo = 'bar'</code-example>
<p>Multi-line, linenums=false.</p>
<code-example linenums='false'>
<p>Multi-line, linenums=true.</p>
<code-example linenums='true'>
&lt;hero-details <em>nghost-pmm-5&gt;
&lt;h2 </em>ngcontent-pmm-5&gt;Bah Dah Bing&lt;/h2&gt;
&lt;hero-team <em>ngcontent-pmm-5 </em>nghost-pmm-6&gt;
@ -53,7 +53,7 @@
&lt;/hero-details&gt;
</code-example>
<p>Default linenums.</p>
<p>Default linenums (false).</p>
<code-example>
&lt;hero-details <em>nghost-pmm-5&gt;
&lt;h2 </em>ngcontent-pmm-5&gt;Mister Fantastic&lt;/h2&gt;