Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

Commit 1324085

Browse files
Eric Jimeneznaomiblack
Eric Jimenez
authored and
naomiblack
committed
feat(api docs): use partials for api docs. Implement deprecated and security notes section
1 parent 7570dc5 commit 1324085

10 files changed

+96
-38
lines changed

‎tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js

+9-1
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ module.exports = function addJadeDataDocsProcessor() {
7474
stability = 'experimental';
7575
} else if (_.has(exportDoc, 'deprecated')) {
7676
stability = 'deprecated';
77+
exportDoc.showDeprecatedNotes = true;
7778
}
7879

7980
var howToUse = '';
@@ -102,7 +103,14 @@ module.exports = function addJadeDataDocsProcessor() {
102103
// Default is no security risk assessed for api
103104
var security = false;
104105
if (_.has(exportDoc, 'security')) {
105-
security = true;
106+
var securityArray = exportDoc.tags.tags.filter(function(tag) {
107+
return tag.tagName === 'security'
108+
});
109+
110+
// Remove line breaks, there should only be one tag
111+
security = securityArray[0].description.replace(/(\r\n|\n|\r)/gm,"");
112+
113+
exportDoc.showSecurityNotes = true;
106114
}
107115

108116
// Data inserted into jade-data.template.html

‎tools/api-builder/angular.io-package/templates/class.template.html

+16-30
Original file line numberDiff line numberDiff line change
@@ -5,36 +5,22 @@
55
{% block body %}
66
include {$ relativePath(doc.path, '_util-fns') $}
77

8-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
9-
div(flex="20" flex-xs="100")
10-
h2(class="h2-api-docs") What it does
11-
div(flex="80" flex-xs="100")
12-
:marked
13-
{%- if doc.whatItDoes %}
14-
{$ doc.whatItDoes | indentForMarkdown(6) $}
15-
{% else %}
16-
*Not yet documented*
17-
{% endif %}
8+
{% include "layout/_what-it-does.html" %}
189

19-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
20-
div(flex="20" flex-xs="100")
21-
h2(class="h2-api-docs") How to use
22-
div(flex="80" flex-xs="100")
23-
:marked
24-
{%- if doc.howToUse %}
25-
{$ doc.howToUse | indentForMarkdown(6) $}
26-
{% else %}
27-
*Not yet documented*
28-
{% endif %}
10+
{% include "layout/_security-notes.html" %}
11+
12+
{% include "layout/_deprecated-notes.html" %}
13+
14+
{% include "layout/_how-to-use.html" %}
2915

30-
.div(layout="row" layout-xs="column" class="ng-cloak")
16+
div(layout="row" layout-xs="column" class="ng-cloak")
3117
div(flex="20" flex-xs="100")
3218
h2(class="h2-api-docs") Class Overview
3319
div(flex="80" flex-xs="100")
3420
code(class="no-bg api-doc-code openParens") class {$ doc.name $} {
3521

3622
{% if doc.statics.length %}
37-
.div(layout="column")
23+
div(layout="column")
3824
{% for member in doc.statics %}{% if not member.internal %}
3925
pre(class="prettyprint no-bg-with-indent")
4026
a(class="code-anchor" href="#{$ member.name $}-anchor")
@@ -43,14 +29,14 @@
4329
{% endif %}{% endfor %}
4430
{% endif %}
4531
{% if doc.constructorDoc.name %}
46-
.div(layout="column")
32+
div(layout="column")
4733
pre(class="prettyprint no-bg-with-indent")
4834
a(class="code-anchor" href="#constructor")
4935
code(class="code-background api-doc-code") {$ doc.constructorDoc.name $}
5036
code(class="api-doc-code") {$ paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $}
5137
{% endif %}
5238
{% if doc.members.length %}
53-
.div(layout="column")
39+
div(layout="column")
5440
{% for member in doc.members %}{% if not member.internal %}
5541
pre(class="prettyprint no-bg-with-indent")
5642
a(class="code-anchor" href="#{$ member.name $}-anchor")
@@ -64,7 +50,7 @@
6450
{% block additional %}
6551
{% endblock %}
6652

67-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
53+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
6854
div(flex="20" flex-xs="100")
6955
h2(class="h2-api-docs") Class Description
7056
div(class="code-links" flex="80" flex-xs="100")
@@ -73,7 +59,7 @@
7359
{$ doc.description | indentForMarkdown(6) | trimBlankLines $}
7460
{% endif %}
7561

76-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
62+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
7763
div(flex="20" flex-xs="100")
7864
h2(class="h2-api-docs") Class Export
7965
div(flex="80" flex-xs="100")
@@ -83,7 +69,7 @@
8369

8470
{%- if doc.decorators.length %}
8571
{% block annotations %}
86-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
72+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
8773
div(flex="20" flex-xs="100")
8874
h2(class="h2-api-docs") Annotations
8975
div(flex="80" flex-xs="100")
@@ -100,7 +86,7 @@
10086
{% endif %}
10187

10288
{%- if doc.constructorDoc and not doc.constructorDoc.internal %}
103-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
89+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
10490
div(flex="20" flex-xs="100")
10591
h2(class="h2-api-docs") Constructor
10692
div(flex="80" flex-xs="100")
@@ -115,7 +101,7 @@
115101
{% endif %}
116102

117103
{% if doc.statics.length %}
118-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
104+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
119105
div(flex="20" flex-xs="100")
120106
h2(class="h2-api-docs") Static Members
121107
div(class="code-links" flex="80" flex-xs="100")
@@ -137,7 +123,7 @@
137123
{% endif %}
138124

139125
{% if doc.members.length %}
140-
.div(layout="row" layout-xs="column" class="instance-members" class="row-margin ng-cloak")
126+
div(layout="row" layout-xs="column" class="instance-members" class="row-margin ng-cloak")
141127
div(flex="20" flex-xs="100")
142128
h2(class="h2-api-docs") Class Details
143129
div(class="code-links" flex="80" flex-xs="100")

‎tools/api-builder/angular.io-package/templates/decorator.template.html

+9-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,15 @@
55
{% block body %}
66
include {$ relativePath(doc.path, '_util-fns') $}
77

8-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
8+
{% include "layout/_what-it-does.html" %}
9+
10+
{% include "layout/_security-notes.html" %}
11+
12+
{% include "layout/_deprecated-notes.html" %}
13+
14+
{% include "layout/_how-to-use.html" %}
15+
16+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
917
div(flex="20" flex-xs="100")
1018
h2(class="h2-api-docs") Variable Export
1119
div(class="code-links" flex="80" flex-xs="100")

‎tools/api-builder/angular.io-package/templates/directive.template.html

+4-4
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
{% block additional -%}
99

1010
{%- if doc.directiveOptions.selector.split(',').length %}
11-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
11+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
1212
div(flex="20" flex-xs="100")
1313
h2(class="h2-api-docs") Selectors
1414
div(flex="80" flex-xs="100")
@@ -19,7 +19,7 @@
1919
{% endif %}
2020

2121
{% if doc.outputs %}
22-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
22+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
2323
div(flex="20" flex-xs="100")
2424
h2(class="h2-api-docs") Outputs
2525
div(flex="80" flex-xs="100")
@@ -34,7 +34,7 @@
3434
{% endif %}
3535

3636
{% if doc.inputs %}
37-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
37+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
3838
div(flex="20" flex-xs="100")
3939
h2(class="h2-api-docs") Inputs
4040
div(flex="80" flex-xs="100")
@@ -49,7 +49,7 @@
4949
{% endif %}
5050

5151
{%- if doc.directiveOptions.exportAs %}
52-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
52+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
5353
div(flex="20" flex-xs="100")
5454
h2(class="h2-api-docs") Exported as
5555
div(flex="80" flex-xs="100")

‎tools/api-builder/angular.io-package/templates/function.template.html

+9-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,15 @@
55
{% block body %}
66
include {$ relativePath(doc.path, '_util-fns') $}
77

8-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
8+
{% include "layout/_what-it-does.html" %}
9+
10+
{% include "layout/_security-notes.html" %}
11+
12+
{% include "layout/_deprecated-notes.html" %}
13+
14+
{% include "layout/_how-to-use.html" %}
15+
16+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
917
div(flex="20" flex-xs="100")
1018
h2(class="h2-api-docs") Class Export
1119
div(class="code-links" flex="80" flex-xs="100")

‎tools/api-builder/angular.io-package/templates/layout/_deprecated-notes.html

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{% if doc.showDeprecatedNotes %}
2+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
3+
div(flex="20" flex-xs="100")
4+
h2(class="h2-api-docs") Deprecation Notes
5+
div(flex="80" flex-xs="100")
6+
:marked
7+
{%- if doc.deprecated %}
8+
{$ doc.deprecated | indentForMarkdown(6) $}
9+
{% else %}
10+
*Not yet documented*
11+
{% endif %}
12+
{% endif %}

‎tools/api-builder/angular.io-package/templates/layout/_how-to-use.html

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
2+
div(flex="20" flex-xs="100")
3+
h2(class="h2-api-docs") How to use
4+
div(flex="80" flex-xs="100")
5+
:marked
6+
{%- if doc.howToUse %}
7+
{$ doc.howToUse | indentForMarkdown(6) $}
8+
{% else %}
9+
*Not yet documented*
10+
{% endif %}

‎tools/api-builder/angular.io-package/templates/layout/_security-notes.html

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{% if doc.showSecurityNotes and doc.security %}
2+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
3+
div(flex="20" flex-xs="100")
4+
h2(class="h2-api-docs") Security Risk
5+
div(flex="80" flex-xs="100")
6+
:marked
7+
{$ doc.security | indentForMarkdown(6) $}
8+
{% endif %}

‎tools/api-builder/angular.io-package/templates/layout/_what-it-does.html

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
2+
div(flex="20" flex-xs="100")
3+
h2(class="h2-api-docs") What it does
4+
div(flex="80" flex-xs="100")
5+
:marked
6+
{%- if doc.whatItDoes %}
7+
{$ doc.whatItDoes | indentForMarkdown(6) $}
8+
{% else %}
9+
*Not yet documented*
10+
{% endif %}

‎tools/api-builder/angular.io-package/templates/var.template.html

+9-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,15 @@
55
{% block body %}
66
include {$ relativePath(doc.path, '_util-fns') $}
77

8-
.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
8+
{% include "layout/_what-it-does.html" %}
9+
10+
{% include "layout/_security-notes.html" %}
11+
12+
{% include "layout/_deprecated-notes.html" %}
13+
14+
{% include "layout/_how-to-use.html" %}
15+
16+
div(layout="row" layout-xs="column" class="row-margin ng-cloak")
917
div(flex="20" flex-xs="100")
1018
h2(class="h2-api-docs") Variable Export
1119
div(class="code-links" flex="80" flex-xs="100")

0 commit comments

Comments
 (0)