build(docs-infra): improve directive API doc templates #25768

petebacondarwin · 2018-08-31T14:59:03Z

Closes #22790
Closes #25530

mary-poppins · 2018-08-31T15:08:00Z

You can preview 3db2590 at https://pr25768-3db2590.ngbuilds.io/.

petebacondarwin · 2018-09-02T13:13:24Z

Some examples:

https://pr25768-3db2590.ngbuilds.io/api/common/NgClass

https://pr25768-3db2590.ngbuilds.io/api/forms/NgForm

https://pr25768-3db2590.ngbuilds.io/api/forms/DefaultValueAccessor

https://pr25768-3db2590.ngbuilds.io/api/router/RouterLinkActive

jenniferfell · 2018-09-06T21:33:49Z

notes from mtg 9/6:
selectors: no table. no indent. UL. 1 LI per selector.
all tables: no code inside table, very long description or code link to "Usage notes" section
move inputs and outputs into properties table?
idea: separate these?

properties
inherited properties
methods
inherited methods (inherited from x)
idea: remove class sig from top - everything is described below (for directives)
idea: "selector usage" section instead of generated selector, hand-craft content instead
idea: exports as - "template variable references" is ok. change var to mytemplatevar or myvarname.

mary-poppins · 2018-09-20T13:04:41Z

You can preview d5b4625 at https://pr25768-d5b4625.ngbuilds.io/.

mary-poppins · 2018-09-21T10:52:23Z

You can preview 06bdf9b at https://pr25768-06bdf9b.ngbuilds.io/.

mary-poppins · 2018-09-21T13:14:55Z

You can preview 029962b at https://pr25768-029962b.ngbuilds.io/.

mary-poppins · 2018-09-21T13:40:29Z

You can preview 0763676 at https://pr25768-0763676.ngbuilds.io/.

mary-poppins · 2018-09-21T20:17:10Z

You can preview 42fd7de at https://pr25768-42fd7de.ngbuilds.io/.

mary-poppins · 2018-09-22T18:58:56Z

You can preview 876f92f at https://pr25768-876f92f.ngbuilds.io/.

gkalpak

Random issue:
When a member gets no link (due to disambiguation issues???), then it looks different than the rest (example):

gkalpak · 2018-09-25T11:12:11Z

aio/tools/transforms/templates/api/lib/memberHelpers.html

@@ -28,12 +28,14 @@
 {%- endmacro -%}

 {%- macro renderMemberSyntax(member, truncateLines) -%}
+    {%- if member.boundTo %}<span class="property-binding">@{$ member.boundTo.type $}({$ member.boundTo.bindingName $})</span>
+{% endif %}


Why the weird indentation?

This is because we need a new line after the @Input(...) text. But I think I can use <br> to get the same effect...

gkalpak · 2018-09-25T12:02:09Z

aio/tools/transforms/templates/api/includes/class-overview.html

@@ -6,5 +6,5 @@
 {% if doc.isAbstract %}abstract {% endif%}class {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} {{$ memberHelper.renderMembers(doc) $}
 }
 </code-example>
-{$ descendants.renderDescendants(doc, 'class', 'Subclasses') $}
+{$ descendants.renderDescendants(doc, 'class', 'Subclasses', true, r/class|directive|pipe|decorator/) $}


What about component?

There are no components in the angular/angular repo.

gkalpak · 2018-09-25T12:02:23Z

aio/tools/transforms/templates/api/includes/interface-overview.html

@@ -6,5 +6,5 @@
 }
 </code-example>
 {$ descendants.renderDescendants(doc, 'interface', 'Child interfaces') $}
-{$ descendants.renderDescendants(doc, 'class', 'Class implementations') $}
+{$ descendants.renderDescendants(doc, 'class', 'Class implementations', true, r/class|directive|pipe|decorator/) $}


What about component?

see #25768 (comment)

gkalpak · 2018-09-25T12:02:53Z

aio/tools/transforms/templates/api/lib/descendants.html

    </li>
  {% endfor %}
 </ul>
 {% endif %}
 {% endmacro -%}

-{%- macro renderDescendants(doc, docType, title='', recursed=true) %}
-  {% set descendants = doc.descendants | filterByPropertyValue('docType', docType) %}
+{%- macro renderDescendants(doc, descendantType, title='', recursed=true, docTypeMatcher = descendantType) %}


Inconsistent whitespace around = 😁

gkalpak · 2018-09-25T12:26:34Z

aio/tools/transforms/angular-base-package/rendering/hasValues.js

+  const value = obj[propertySegments[index]];
+  return index < (propertySegments.length - 1) ? readProperty(value, propertySegments, index + 1) : value;
+}


It might be safer to support not having an intermediate object at all. E.g.: readProperty({a: {}}, ['a', 'b', 'c'], 0)

gkalpak · 2018-09-25T12:31:26Z

aio/src/styles/2-modules/_api-pages.scss

@@ -33,6 +33,7 @@
  .method-table, .option-table, .list-table {
    td > code {
      background-color: inherit;
+      white-space: pre;


Now that whitespace is significant, helpers that render inside these code blocks (renderMemberSyntax or similar) need to be more "careful" to avoid:

_{I manually tweaked the last entry to remove whitespace.}

fixed in 8d644ee

gkalpak · 2018-09-25T12:45:41Z

aio/tools/transforms/templates/api/lib/memberHelpers.html

  <table class="is-full-width list-table property-table">
    <thead>
      <tr>
        <th>{$ headings[0] or 'Property' $}</th>
-        {% if hasTypes %}<th>{$ headings[1] or 'Type' $}</th>{% endif %}


Now that headings[1] is not used, it should be "removed" (i.e. remove it from all call-sites that specify it and get the description heading from headings[1] (instead of headings[2])).

IgorMinar · 2018-09-25T18:12:20Z

in the properties table we need to quote the prop value: @Input(foo) -> @Input("foo")
presentation of getters and setters should be consistent. I think we should actually drop the "get" and "set" prefix for the props and use display only read-only and write-only if necessary. set foo -> foo write-only

#25768) PR Close #25768

PR Close #25768

…25768) PR Close #25768

) PR Close #25768

`:not(...)` blocks are now rendered as italic, while the rest of the selector is bold. PR Close #25768

PR Close #25768

If there is additional (non-short) description then add in a link to the short description to take the reader there. PR Close #25768

PR Close #25768

Now that `list-table` cells are `pre` formatterd we must be careful of what whitespace appears in text nodes. PR Close #25768

) (This was added in 405d974 but it is not clear the reasoning. It looks better to remove it now.) PR Close #25768

Closes angular#22790 Closes angular#25530 PR Close angular#25768

If the documentation contains a `@selectors` tag then the content of that is used to describe the selectors of a directive. Otherwise the selector string is split and each selector is listed as a list item in an unordered list. PR Close angular#25768

…r#25768) PR Close angular#25768

angular#25768) PR Close angular#25768

PR Close angular#25768

…5768) PR Close angular#25768

…ngular#25768) PR Close angular#25768

…ular#25768) PR Close angular#25768

`:not(...)` blocks are now rendered as italic, while the rest of the selector is bold. PR Close angular#25768

…lar#25768) PR Close angular#25768

If there is additional (non-short) description then add in a link to the short description to take the reader there. PR Close angular#25768

PR Close angular#25768

…r#25768) Now that `list-table` cells are `pre` formatterd we must be careful of what whitespace appears in text nodes. PR Close angular#25768

…ular#25768) (This was added in 405d974 but it is not clear the reasoning. It looks better to remove it now.) PR Close angular#25768

angular-automatic-lock-bot · 2019-09-14T10:22:53Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

petebacondarwin added action: review The PR is still awaiting reviews from at least one requested reviewer effort1: hours severity1: confusing target: patch This PR is targeted for the next patch release labels Aug 31, 2018

petebacondarwin added this to the Backlog milestone Aug 31, 2018

googlebot added the cla: yes label Aug 31, 2018

ngbot bot modified the milestones: Backlog, needsTriage Aug 31, 2018

petebacondarwin requested a review from IgorMinar August 31, 2018 14:59

petebacondarwin added this to REVIEW in docs-infra Aug 31, 2018

jenniferfell added comp: docs/api and removed subtype: docs-design labels Sep 13, 2018

petebacondarwin force-pushed the aio-directve-improvements branch from 3db2590 to d5b4625 Compare September 20, 2018 12:57

This was referenced Sep 20, 2018

FormGroup has many links incorrectly going to AbstractControl methods #19387

Closed

aio + docs/api: directive docs ideas #22790

Closed

petebacondarwin force-pushed the aio-directve-improvements branch from d5b4625 to 06bdf9b Compare September 21, 2018 10:44

petebacondarwin force-pushed the aio-directve-improvements branch from 0763676 to 42fd7de Compare September 21, 2018 20:09

gkalpak reviewed Sep 25, 2018

View reviewed changes

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): rename example template variable in directive pages (

d0f7ead

#25768) PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): directive inputs and outputs (#25768)

9889276

PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): display inherited members on directives (#25768)

ce06a75

PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): include directives etc in class descendants lists (#…

15dadb9

…25768) PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): move directive macros into memberHelpers.html (#25768

f4b6058

) PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): improve directive selector rendering (#25768)

935ef13

`:not(...)` blocks are now rendered as italic, while the rest of the selector is bold. PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): pluralize NgModule(s) heading as appropriate (#25768)

4b1fd98

PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): add short description "See more" link (#25768)

d22418d

If there is additional (non-short) description then add in a link to the short description to take the reader there. PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): remove unused property table heading (#25768)

783a682

PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): simplify property syntax rendering (#25768)

7373da9

PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

build(docs-infra): fix formatting of entry point export table (#25768)

5977b72

Now that `list-table` cells are `pre` formatterd we must be careful of what whitespace appears in text nodes. PR Close #25768

alxhub pushed a commit that referenced this pull request Oct 1, 2018

fix(docs-infra): remove unnecessary margin on short descriptions (#25768

a2878b0

) (This was added in 405d974 but it is not clear the reasoning. It looks better to remove it now.) PR Close #25768

petebacondarwin deleted the aio-directve-improvements branch December 12, 2018 08:28

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): improve directive API doc templates (angular#25768)

151e8f4

Closes angular#22790 Closes angular#25530 PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): remove class overview from directive pages (angula…

c85f38a

…r#25768) PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): rename example template variable in directive pages (

95db40b

angular#25768) PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): directive inputs and outputs (angular#25768)

c4fb121

PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): display inherited members on directives (angular#2…

b42093c

…5768) PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): include directives etc in class descendants lists (a…

e299a10

…ngular#25768) PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): move directive macros into memberHelpers.html (ang…

1f08300

…ular#25768) PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): pluralize NgModule(s) heading as appropriate (angu…

55ade43

…lar#25768) PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): remove unused property table heading (angular#25768)

b75cbf7

PR Close angular#25768

FrederikSchlemmer pushed a commit to FrederikSchlemmer/angular that referenced this pull request Jan 3, 2019

build(docs-infra): simplify property syntax rendering (angular#25768)

c63adfc

PR Close angular#25768

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 14, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

build(docs-infra): improve directive API doc templates #25768

build(docs-infra): improve directive API doc templates #25768

petebacondarwin commented Aug 31, 2018

mary-poppins commented Aug 31, 2018

petebacondarwin commented Sep 2, 2018

jenniferfell commented Sep 6, 2018

mary-poppins commented Sep 20, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 22, 2018

gkalpak left a comment

gkalpak Sep 25, 2018

petebacondarwin Sep 26, 2018

gkalpak Sep 25, 2018

petebacondarwin Sep 26, 2018

gkalpak Sep 25, 2018

petebacondarwin Sep 26, 2018

gkalpak Sep 25, 2018

gkalpak Sep 25, 2018

gkalpak Sep 25, 2018

petebacondarwin Sep 26, 2018

gkalpak Sep 25, 2018

IgorMinar commented Sep 25, 2018 •

edited by petebacondarwin

angular-automatic-lock-bot bot commented Sep 14, 2019

build(docs-infra): improve directive API doc templates #25768

build(docs-infra): improve directive API doc templates #25768

Conversation

petebacondarwin commented Aug 31, 2018

mary-poppins commented Aug 31, 2018

petebacondarwin commented Sep 2, 2018

jenniferfell commented Sep 6, 2018

mary-poppins commented Sep 20, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 21, 2018

mary-poppins commented Sep 22, 2018

gkalpak left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

IgorMinar commented Sep 25, 2018 • edited by petebacondarwin

angular-automatic-lock-bot bot commented Sep 14, 2019

IgorMinar commented Sep 25, 2018 •

edited by petebacondarwin