From f22deb2e2d93ca307fde1ebac2b5ae9715db4b60 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Fri, 31 Aug 2018 15:57:53 +0100 Subject: [PATCH] build(docs-infra): improve directive API doc templates (#25768) Closes #22790 Closes #25530 PR Close #25768 --- aio/src/styles/2-modules/_api-pages.scss | 4 ++ aio/src/styles/2-modules/_code.scss | 1 + .../processors/matchUpDirectiveDecorators.js | 2 + .../rendering/hasValues.js | 18 ++++++++- .../rendering/hasValues.spec.js | 34 +++++++++++++--- .../templates/api/class.template.html | 14 +------ .../templates/api/directive.template.html | 28 ++++++++++--- .../templates/api/export-base.template.html | 2 +- .../templates/api/includes/class-members.html | 14 +++++++ .../api/includes/class-overview.html | 1 + .../templates/api/includes/export-as.html | 21 ++++++++-- .../templates/api/includes/selectors.html | 18 +++++++-- .../templates/api/lib/directiveHelpers.html | 39 ++++++++++++++++--- 13 files changed, 155 insertions(+), 41 deletions(-) create mode 100644 aio/tools/transforms/templates/api/includes/class-members.html diff --git a/aio/src/styles/2-modules/_api-pages.scss b/aio/src/styles/2-modules/_api-pages.scss index 81e39b50a4..e664178343 100644 --- a/aio/src/styles/2-modules/_api-pages.scss +++ b/aio/src/styles/2-modules/_api-pages.scss @@ -31,6 +31,10 @@ } .method-table, .option-table, .list-table { + td > code { + background-color: inherit; + } + .with-github-links { align-items: center; display: flex; diff --git a/aio/src/styles/2-modules/_code.scss b/aio/src/styles/2-modules/_code.scss index 173f524274..98749dd37c 100644 --- a/aio/src/styles/2-modules/_code.scss +++ b/aio/src/styles/2-modules/_code.scss @@ -137,6 +137,7 @@ aio-code pre { .sidenav-content code a { color: inherit; font-size: inherit; + font-weight: inherit; } /* PRETTY PRINTING STYLES for prettify.js. */ diff --git a/aio/tools/transforms/angular-api-package/processors/matchUpDirectiveDecorators.js b/aio/tools/transforms/angular-api-package/processors/matchUpDirectiveDecorators.js index 9557ceac2b..23893c7adf 100644 --- a/aio/tools/transforms/angular-api-package/processors/matchUpDirectiveDecorators.js +++ b/aio/tools/transforms/angular-api-package/processors/matchUpDirectiveDecorators.js @@ -21,7 +21,9 @@ module.exports = function matchUpDirectiveDecorators() { if (doc.docType === 'directive') { doc.selector = stripQuotes(doc.directiveOptions.selector); + doc.selectorArray = doc.selector ? doc.selector.split(',') : []; doc.exportAs = stripQuotes(doc.directiveOptions.exportAs); + doc.exportAsArray = doc.exportAs ? doc.exportAs.split(',') : []; doc.inputs = getBindingInfo(doc.directiveOptions.inputs, doc.members, 'Input'); doc.outputs = getBindingInfo(doc.directiveOptions.outputs, doc.members, 'Output'); diff --git a/aio/tools/transforms/angular-base-package/rendering/hasValues.js b/aio/tools/transforms/angular-base-package/rendering/hasValues.js index 7b15501fa2..c9578adc93 100644 --- a/aio/tools/transforms/angular-base-package/rendering/hasValues.js +++ b/aio/tools/transforms/angular-base-package/rendering/hasValues.js @@ -3,7 +3,21 @@ module.exports = function hasValues() { name: 'hasValues', process: function(list, property) { if (!list || !Array.isArray(list)) return false; - return list.some(item => item[property]); + return list.some(item => readProperty(item, property.split('.'), 0)); } }; -}; \ No newline at end of file +}; + +/** + * Search deeply into an object via a collection of property segments, starting at the + * indexed segment. + * + * E.g. if `obj = { a: { b: { c: 10 }}}` then + * `readProperty(obj, ['a', 'b', 'c'], 0)` will return true; + * but + * `readProperty(obj, ['a', 'd'], 0)` will return false; + */ +function readProperty(obj, propertySegments, index) { + const value = obj[propertySegments[index]]; + return !!value && (index === propertySegments.length - 1 || readProperty(value, propertySegments, index + 1)); +} diff --git a/aio/tools/transforms/angular-base-package/rendering/hasValues.spec.js b/aio/tools/transforms/angular-base-package/rendering/hasValues.spec.js index 7b057bcafd..c260f5d17a 100644 --- a/aio/tools/transforms/angular-base-package/rendering/hasValues.spec.js +++ b/aio/tools/transforms/angular-base-package/rendering/hasValues.spec.js @@ -7,13 +7,37 @@ describe('hasValues filter', () => { it('should be called "hasValues"', function() { expect(filter.name).toEqual('hasValues'); }); - it('should return true if the specified property is truthy on any item in the list', function() { - expect(filter.process([], 'a')).toEqual(false); - expect(filter.process(0, 'a')).toEqual(false); - expect(filter.process({}, 'a')).toEqual(false); + it('should return true if the specified property path is truthy on any item in the list', function() { expect(filter.process([{a: 1}], 'a')).toEqual(true); - expect(filter.process([{b: 2}], 'a')).toEqual(false); expect(filter.process([{a: 1, b: 2}], 'a')).toEqual(true); expect(filter.process([{b: 2}, {a: 1}], 'a')).toEqual(true); + + expect(filter.process([{a:{b:1}}], 'a.b')).toEqual(true); + expect(filter.process([{a:{b:1}, b: 2}], 'a.b')).toEqual(true); + expect(filter.process([{b: 2}, {a:{b:1}}], 'a.b')).toEqual(true); + }); + + it('should return false if the value is not an object', () => { + expect(filter.process([], 'a')).toEqual(false); + expect(filter.process(0, 'a')).toEqual(false); + expect(filter.process([], 'a.b')).toEqual(false); + expect(filter.process(0, 'a.b')).toEqual(false); + }); + + it('should return false if the property exists but is falsy', () => { + expect(filter.process([{a: false}], 'a')).toEqual(false); + expect(filter.process([{a: ''}], 'a')).toEqual(false); + expect(filter.process([{a: 0}], 'a')).toEqual(false); + expect(filter.process([{a: null}], 'a')).toEqual(false); + expect(filter.process([{a: undefined}], 'a')).toEqual(false); + }); + + it('should return false if any of the properties in the path do not exist', () => { + expect(filter.process({}, 'a')).toEqual(false); + expect(filter.process({}, 'a.b')).toEqual(false); + + expect(filter.process([{b: 2}], 'a')).toEqual(false); + expect(filter.process([{a: 2}], 'a.b')).toEqual(false); + expect(filter.process([{a: {}}], 'a.b.c')).toEqual(false); }); }); \ No newline at end of file diff --git a/aio/tools/transforms/templates/api/class.template.html b/aio/tools/transforms/templates/api/class.template.html index 7446b43216..50d52311e6 100644 --- a/aio/tools/transforms/templates/api/class.template.html +++ b/aio/tools/transforms/templates/api/class.template.html @@ -1,21 +1,9 @@ -{% import "lib/memberHelpers.html" as memberHelpers -%} -{% import "lib/descendants.html" as descendants -%} -{% import "lib/paramList.html" as params -%} {% extends 'export-base.template.html' -%} {% block overview %} {% include "includes/class-overview.html" %} {% endblock %} {% block details %} - {% block additional %}{% endblock %} {% include "includes/description.html" %} - {$ memberHelpers.renderProperties(doc.staticProperties, 'static-properties', 'static-property', 'Static properties') $} - {$ memberHelpers.renderMethodDetails(versionInfo, doc.staticMethods, 'static-methods', 'static-method', 'Static methods') $} - {% if doc.constructorDoc %} -

Constructor

- {$ memberHelpers.renderMethodDetail(versionInfo, doc.constructorDoc, 'constructor') $}{% endif %} - - {$ memberHelpers.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $} - - {$ memberHelpers.renderMethodDetails(versionInfo, doc.methods, 'instance-methods', 'instance-method', 'Methods') $} + {% include "includes/class-members.html" %} {% endblock %} diff --git a/aio/tools/transforms/templates/api/directive.template.html b/aio/tools/transforms/templates/api/directive.template.html index daeae4e526..d49a2402bf 100644 --- a/aio/tools/transforms/templates/api/directive.template.html +++ b/aio/tools/transforms/templates/api/directive.template.html @@ -1,14 +1,30 @@ {% import "lib/directiveHelpers.html" as directiveHelper -%} -{% import "lib/paramList.html" as params -%} {% extends 'class.template.html' -%} -{% block overview %}{% include "includes/directive-overview.html" %}{% endblock %} -{% block additional -%} -{% include "includes/ngmodule.html" %} -{% include "includes/selectors.html" %} +{% block overview %}{% endblock %} + +{% block details -%} + {% include "includes/ngmodule.html" %} + {% include "includes/selectors.html" %} + {$ directiveHelper.renderBindings(doc.inputs, 'inputs', 'input', 'Inputs') $} + {$ directiveHelper.renderBindings(doc.outputs, 'outputs', 'output', 'Outputs') $} + {% include "includes/export-as.html" %} + + {% if doc.description or doc.usageNotes %} +
+

Description

+ {$ (doc.description or '') | trimBlankLines | marked $} + {$ (doc.usageNotes or '') | trimBlankLines | marked $} +
+ {% endif %} + +

Class

+ {% include "includes/directive-overview.html" %} + + {% include "includes/class-members.html" %} {% endblock %} -{% block annotations %}{% endblock %} +{% block endNotes %}{% endblock %} \ No newline at end of file diff --git a/aio/tools/transforms/templates/api/export-base.template.html b/aio/tools/transforms/templates/api/export-base.template.html index 2d42946f44..94a02eb1a8 100644 --- a/aio/tools/transforms/templates/api/export-base.template.html +++ b/aio/tools/transforms/templates/api/export-base.template.html @@ -7,5 +7,5 @@ {% block overview %}{% endblock %} {% include "includes/see-also.html" %} {% block details %}{% endblock %} - {% include "includes/usageNotes.html" %} + {% block endNotes %}{% include "includes/usageNotes.html" %}{% endblock %} {% endblock %} diff --git a/aio/tools/transforms/templates/api/includes/class-members.html b/aio/tools/transforms/templates/api/includes/class-members.html new file mode 100644 index 0000000000..7faf3ebaa7 --- /dev/null +++ b/aio/tools/transforms/templates/api/includes/class-members.html @@ -0,0 +1,14 @@ +{% import "lib/memberHelpers.html" as memberHelpers -%} + +{$ memberHelpers.renderProperties(doc.staticProperties, 'static-properties', 'static-property', 'Static properties') $} + +{$ memberHelpers.renderMethodDetails(versionInfo, doc.staticMethods, 'static-methods', 'static-method', 'Static methods') $} + +{% if doc.constructorDoc %} +

Constructor

+{$ memberHelpers.renderMethodDetail(versionInfo, doc.constructorDoc, 'constructor') $} +{% endif %} + +{$ memberHelpers.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $} + +{$ memberHelpers.renderMethodDetails(versionInfo, doc.methods, 'instance-methods', 'instance-method', 'Methods') $} diff --git a/aio/tools/transforms/templates/api/includes/class-overview.html b/aio/tools/transforms/templates/api/includes/class-overview.html index c312d557c1..03807862a1 100644 --- a/aio/tools/transforms/templates/api/includes/class-overview.html +++ b/aio/tools/transforms/templates/api/includes/class-overview.html @@ -1,4 +1,5 @@ {% import "lib/memberHelpers.html" as memberHelper -%} +{% import "lib/descendants.html" as descendants -%}
diff --git a/aio/tools/transforms/templates/api/includes/export-as.html b/aio/tools/transforms/templates/api/includes/export-as.html index a3fed860db..880b824a3a 100644 --- a/aio/tools/transforms/templates/api/includes/export-as.html +++ b/aio/tools/transforms/templates/api/includes/export-as.html @@ -1,8 +1,21 @@ {%- if doc.exportAs %}
-

Exported as

-
- {$ doc.exportAs $} -
+

Template variable references

+ + + + + + + + + {%- for exportAs in doc.exportAsArray %} + + + + + {% endfor %} + +
IdentifierUsage
{$ exportAs $}#var="{$ exportAs $}"
{% endif %} diff --git a/aio/tools/transforms/templates/api/includes/selectors.html b/aio/tools/transforms/templates/api/includes/selectors.html index 0e14513b37..c28f0ed9d9 100644 --- a/aio/tools/transforms/templates/api/includes/selectors.html +++ b/aio/tools/transforms/templates/api/includes/selectors.html @@ -1,9 +1,19 @@ {%- if doc.selector %}

Selectors

- - {%- for selector in doc.selector.split(',') %} - {$ selector $}{% endfor %} - + + + + + + + + {%- for selector in doc.selectorArray %} + + + + {% endfor %} + +
Selector
{$ selector $}
{% endif %} diff --git a/aio/tools/transforms/templates/api/lib/directiveHelpers.html b/aio/tools/transforms/templates/api/lib/directiveHelpers.html index 937f02b891..5e0ddf91e6 100644 --- a/aio/tools/transforms/templates/api/lib/directiveHelpers.html +++ b/aio/tools/transforms/templates/api/lib/directiveHelpers.html @@ -1,13 +1,40 @@ {% macro renderBindings(bindings, cssContainerClass, cssItemClass, title) -%} +{% set hasDescription = bindings | hasValues('memberDoc.description') %} +{% set hasTypes = bindings | hasValues('memberDoc.type') %} {% if bindings.length %}

{$ title $}

- {% for binding in bindings %} -
- {$ binding.bindingName $} bound to {$ binding.memberDoc.containerDoc.name $}.{$ binding.propertyName $} - {#{$ binding.memberDoc.description | trimBlankLines | marked $}#} -
+ + + + + {% if hasTypes %}{% endif %} + {% if hasDescription %}{% endif %} + + + + {% for binding in bindings %} + + + {% if hasTypes %} + + {% endif %} + {% if hasDescription %} + + {% endif %} + {% endfor %} + +
BindingTypeDescription
+ {$ binding.bindingName $} + {%- if binding.bindingName != binding.propertyName %} ({$ binding.propertyName $}){% endif-%} + + + {$ binding.memberDoc.shortDescription | marked $} + {$ binding.memberDoc.description | marked $} +
{% endif %} -{%- endmacro %} \ No newline at end of file +{%- endmacro %} + +