From 1324085c0c5d200919993939759165117067ae2e Mon Sep 17 00:00:00 2001 From: Eric Jimenez Date: Wed, 1 Jun 2016 10:33:38 -0400 Subject: [PATCH] feat(api docs): use partials for api docs. Implement deprecated and security notes section --- .../processors/addJadeDataDocsProcessor.js | 10 +++- .../templates/class.template.html | 46 +++++++------------ .../templates/decorator.template.html | 10 +++- .../templates/directive.template.html | 8 ++-- .../templates/function.template.html | 10 +++- .../templates/layout/_deprecated-notes.html | 12 +++++ .../templates/layout/_how-to-use.html | 10 ++++ .../templates/layout/_security-notes.html | 8 ++++ .../templates/layout/_what-it-does.html | 10 ++++ .../templates/var.template.html | 10 +++- 10 files changed, 96 insertions(+), 38 deletions(-) create mode 100644 tools/api-builder/angular.io-package/templates/layout/_deprecated-notes.html create mode 100644 tools/api-builder/angular.io-package/templates/layout/_how-to-use.html create mode 100644 tools/api-builder/angular.io-package/templates/layout/_security-notes.html create mode 100644 tools/api-builder/angular.io-package/templates/layout/_what-it-does.html diff --git a/tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js b/tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js index d9edc7ccfd..b3fde862f5 100644 --- a/tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js +++ b/tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js @@ -74,6 +74,7 @@ module.exports = function addJadeDataDocsProcessor() { stability = 'experimental'; } else if (_.has(exportDoc, 'deprecated')) { stability = 'deprecated'; + exportDoc.showDeprecatedNotes = true; } var howToUse = ''; @@ -102,7 +103,14 @@ module.exports = function addJadeDataDocsProcessor() { // Default is no security risk assessed for api var security = false; if (_.has(exportDoc, 'security')) { - security = true; + var securityArray = exportDoc.tags.tags.filter(function(tag) { + return tag.tagName === 'security' + }); + + // Remove line breaks, there should only be one tag + security = securityArray[0].description.replace(/(\r\n|\n|\r)/gm,""); + + exportDoc.showSecurityNotes = true; } // Data inserted into jade-data.template.html diff --git a/tools/api-builder/angular.io-package/templates/class.template.html b/tools/api-builder/angular.io-package/templates/class.template.html index 016ce47923..5735b72af4 100644 --- a/tools/api-builder/angular.io-package/templates/class.template.html +++ b/tools/api-builder/angular.io-package/templates/class.template.html @@ -5,36 +5,22 @@ {% block body %} include {$ relativePath(doc.path, '_util-fns') $} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") - div(flex="20" flex-xs="100") - h2(class="h2-api-docs") What it does - div(flex="80" flex-xs="100") - :marked - {%- if doc.whatItDoes %} -{$ doc.whatItDoes | indentForMarkdown(6) $} - {% else %} - *Not yet documented* - {% endif %} +{% include "layout/_what-it-does.html" %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") - div(flex="20" flex-xs="100") - h2(class="h2-api-docs") How to use - div(flex="80" flex-xs="100") - :marked - {%- if doc.howToUse %} -{$ doc.howToUse | indentForMarkdown(6) $} - {% else %} - *Not yet documented* - {% endif %} +{% include "layout/_security-notes.html" %} -.div(layout="row" layout-xs="column" class="ng-cloak") +{% include "layout/_deprecated-notes.html" %} + +{% include "layout/_how-to-use.html" %} + +div(layout="row" layout-xs="column" class="ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Class Overview div(flex="80" flex-xs="100") code(class="no-bg api-doc-code openParens") class {$ doc.name $} { {% if doc.statics.length %} - .div(layout="column") + div(layout="column") {% for member in doc.statics %}{% if not member.internal %} pre(class="prettyprint no-bg-with-indent") a(class="code-anchor" href="#{$ member.name $}-anchor") @@ -43,14 +29,14 @@ include {$ relativePath(doc.path, '_util-fns') $} {% endif %}{% endfor %} {% endif %} {% if doc.constructorDoc.name %} - .div(layout="column") + div(layout="column") pre(class="prettyprint no-bg-with-indent") a(class="code-anchor" href="#constructor") code(class="code-background api-doc-code") {$ doc.constructorDoc.name $} code(class="api-doc-code") {$ paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $} {% endif %} {% if doc.members.length %} - .div(layout="column") + div(layout="column") {% for member in doc.members %}{% if not member.internal %} pre(class="prettyprint no-bg-with-indent") a(class="code-anchor" href="#{$ member.name $}-anchor") @@ -64,7 +50,7 @@ include {$ relativePath(doc.path, '_util-fns') $} {% block additional %} {% endblock %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Class Description div(class="code-links" flex="80" flex-xs="100") @@ -73,7 +59,7 @@ include {$ relativePath(doc.path, '_util-fns') $} {$ doc.description | indentForMarkdown(6) | trimBlankLines $} {% endif %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Class Export div(flex="80" flex-xs="100") @@ -83,7 +69,7 @@ include {$ relativePath(doc.path, '_util-fns') $} {%- if doc.decorators.length %} {% block annotations %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Annotations div(flex="80" flex-xs="100") @@ -100,7 +86,7 @@ include {$ relativePath(doc.path, '_util-fns') $} {% endif %} {%- if doc.constructorDoc and not doc.constructorDoc.internal %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Constructor div(flex="80" flex-xs="100") @@ -115,7 +101,7 @@ include {$ relativePath(doc.path, '_util-fns') $} {% endif %} {% if doc.statics.length %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Static Members div(class="code-links" flex="80" flex-xs="100") @@ -137,7 +123,7 @@ include {$ relativePath(doc.path, '_util-fns') $} {% endif %} {% if doc.members.length %} -.div(layout="row" layout-xs="column" class="instance-members" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="instance-members" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Class Details div(class="code-links" flex="80" flex-xs="100") diff --git a/tools/api-builder/angular.io-package/templates/decorator.template.html b/tools/api-builder/angular.io-package/templates/decorator.template.html index 6d449814cf..7c86eca94d 100644 --- a/tools/api-builder/angular.io-package/templates/decorator.template.html +++ b/tools/api-builder/angular.io-package/templates/decorator.template.html @@ -5,7 +5,15 @@ {% block body %} include {$ relativePath(doc.path, '_util-fns') $} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +{% include "layout/_what-it-does.html" %} + +{% include "layout/_security-notes.html" %} + +{% include "layout/_deprecated-notes.html" %} + +{% include "layout/_how-to-use.html" %} + +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Variable Export div(class="code-links" flex="80" flex-xs="100") diff --git a/tools/api-builder/angular.io-package/templates/directive.template.html b/tools/api-builder/angular.io-package/templates/directive.template.html index 9e8ab62766..4bff9414cb 100644 --- a/tools/api-builder/angular.io-package/templates/directive.template.html +++ b/tools/api-builder/angular.io-package/templates/directive.template.html @@ -8,7 +8,7 @@ {% block additional -%} {%- if doc.directiveOptions.selector.split(',').length %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Selectors div(flex="80" flex-xs="100") @@ -19,7 +19,7 @@ {% endif %} {% if doc.outputs %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Outputs div(flex="80" flex-xs="100") @@ -34,7 +34,7 @@ {% endif %} {% if doc.inputs %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Inputs div(flex="80" flex-xs="100") @@ -49,7 +49,7 @@ {% endif %} {%- if doc.directiveOptions.exportAs %} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Exported as div(flex="80" flex-xs="100") diff --git a/tools/api-builder/angular.io-package/templates/function.template.html b/tools/api-builder/angular.io-package/templates/function.template.html index 00e29907de..7cac55eb24 100644 --- a/tools/api-builder/angular.io-package/templates/function.template.html +++ b/tools/api-builder/angular.io-package/templates/function.template.html @@ -5,7 +5,15 @@ {% block body %} include {$ relativePath(doc.path, '_util-fns') $} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +{% include "layout/_what-it-does.html" %} + +{% include "layout/_security-notes.html" %} + +{% include "layout/_deprecated-notes.html" %} + +{% include "layout/_how-to-use.html" %} + +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Class Export div(class="code-links" flex="80" flex-xs="100") diff --git a/tools/api-builder/angular.io-package/templates/layout/_deprecated-notes.html b/tools/api-builder/angular.io-package/templates/layout/_deprecated-notes.html new file mode 100644 index 0000000000..c350a4c204 --- /dev/null +++ b/tools/api-builder/angular.io-package/templates/layout/_deprecated-notes.html @@ -0,0 +1,12 @@ +{% if doc.showDeprecatedNotes %} +div(layout="row" layout-xs="column" class="row-margin ng-cloak") + div(flex="20" flex-xs="100") + h2(class="h2-api-docs") Deprecation Notes + div(flex="80" flex-xs="100") + :marked + {%- if doc.deprecated %} +{$ doc.deprecated | indentForMarkdown(6) $} + {% else %} + *Not yet documented* + {% endif %} +{% endif %} \ No newline at end of file diff --git a/tools/api-builder/angular.io-package/templates/layout/_how-to-use.html b/tools/api-builder/angular.io-package/templates/layout/_how-to-use.html new file mode 100644 index 0000000000..1c8e738dd9 --- /dev/null +++ b/tools/api-builder/angular.io-package/templates/layout/_how-to-use.html @@ -0,0 +1,10 @@ +div(layout="row" layout-xs="column" class="row-margin ng-cloak") + div(flex="20" flex-xs="100") + h2(class="h2-api-docs") How to use + div(flex="80" flex-xs="100") + :marked + {%- if doc.howToUse %} +{$ doc.howToUse | indentForMarkdown(6) $} + {% else %} + *Not yet documented* + {% endif %} \ No newline at end of file diff --git a/tools/api-builder/angular.io-package/templates/layout/_security-notes.html b/tools/api-builder/angular.io-package/templates/layout/_security-notes.html new file mode 100644 index 0000000000..8cad29266f --- /dev/null +++ b/tools/api-builder/angular.io-package/templates/layout/_security-notes.html @@ -0,0 +1,8 @@ +{% if doc.showSecurityNotes and doc.security %} +div(layout="row" layout-xs="column" class="row-margin ng-cloak") + div(flex="20" flex-xs="100") + h2(class="h2-api-docs") Security Risk + div(flex="80" flex-xs="100") + :marked +{$ doc.security | indentForMarkdown(6) $} +{% endif %} \ No newline at end of file diff --git a/tools/api-builder/angular.io-package/templates/layout/_what-it-does.html b/tools/api-builder/angular.io-package/templates/layout/_what-it-does.html new file mode 100644 index 0000000000..a4e7c58ab6 --- /dev/null +++ b/tools/api-builder/angular.io-package/templates/layout/_what-it-does.html @@ -0,0 +1,10 @@ +div(layout="row" layout-xs="column" class="row-margin ng-cloak") + div(flex="20" flex-xs="100") + h2(class="h2-api-docs") What it does + div(flex="80" flex-xs="100") + :marked + {%- if doc.whatItDoes %} +{$ doc.whatItDoes | indentForMarkdown(6) $} + {% else %} + *Not yet documented* + {% endif %} \ No newline at end of file diff --git a/tools/api-builder/angular.io-package/templates/var.template.html b/tools/api-builder/angular.io-package/templates/var.template.html index 51a8056352..fc9851617e 100644 --- a/tools/api-builder/angular.io-package/templates/var.template.html +++ b/tools/api-builder/angular.io-package/templates/var.template.html @@ -5,7 +5,15 @@ {% block body %} include {$ relativePath(doc.path, '_util-fns') $} -.div(layout="row" layout-xs="column" class="row-margin ng-cloak") +{% include "layout/_what-it-does.html" %} + +{% include "layout/_security-notes.html" %} + +{% include "layout/_deprecated-notes.html" %} + +{% include "layout/_how-to-use.html" %} + +div(layout="row" layout-xs="column" class="row-margin ng-cloak") div(flex="20" flex-xs="100") h2(class="h2-api-docs") Variable Export div(class="code-links" flex="80" flex-xs="100")