build(aio) + docs: miscellaneous updates to the doc-gen by petebacondarwin · Pull Request #24000 · angular/angular

petebacondarwin · 2018-05-18T18:40:09Z

There are quite a lot of commits here but each is fairly self-contained and intuitive.

googlebot · 2018-05-18T18:40:42Z

☹️ Sorry, but only Googlers may change the label cla: yes.

googlebot · 2018-05-18T18:40:50Z

☹️ Sorry, but only Googlers may change the label cla: yes.

mary-poppins · 2018-05-18T18:53:50Z

You can preview af721ca at https://pr24000-af721ca.ngbuilds.io/.

gkalpak

Good stuff 💯
(Only some minor comments.)

gkalpak · 2018-05-21T13:02:56Z

Inconsistent empty line 😁

gkalpak · 2018-05-21T13:05:56Z

While you are at it: Missing period at the end 😁

gkalpak · 2018-05-21T13:07:23Z

This line right below an example sounds weird. Maybe move it above all examples (and change "an example" to "some examples")?

gkalpak · 2018-05-22T07:05:19Z

Having an empty section at the same level as the next one seems odd. Maybe remove this from here (and append "example" in the titles of the sections below)?

gkalpak · 2018-05-22T07:07:16Z

Ohh 😲
_{(There are files below - e.g. packages/core/src/metadata/di.ts - that use See. Just sayin'... 😛)}

I have updated the others to use @see as well.

gkalpak · 2018-05-22T10:16:26Z

Incorrect indentation.

gkalpak · 2018-05-22T10:31:51Z

Incorrect indentation 😱

Indentation still incorrect 😁

I have unindented the section tag which should now solve this problem.

gkalpak · 2018-05-22T10:32:23Z

Is the h3 needed here?

The headings for the properties table also uses H3 here.
I guess we could avoid both and use appropriate changes to CSS.

Actually thinking about this again, I think we should keep H3s here. Although wrapped in a table (for rendering) the semantic meaning is that the name of the option/property is the heading for this section, which describes this option/property.

gkalpak · 2018-05-22T10:35:00Z

Isn't this needed any more?

Correct. It is not needed. We agreed that the options table was a better representation of decorator doc types.

gkalpak · 2018-05-22T10:37:29Z

Does this need the .no-anchor class (as in decorator.template.html)?

I think you are right.

Actually I think that Usage Notes here should perhaps be a H4 since the main heading for this table is the H3 property name.

Even further I decided that there should be no heading at all in this case!

And the same for the decorator case.

petebacondarwin · 2018-05-23T17:45:25Z

OK I fixed up commits based on all those lovely comments. Thanks @gkalpak
I have now noticed two new issues:

we are capturing the docs on the decorator const declaration, which is not really desirable
"Query" (e.g. ViewChild) decorator options are missing. I think this is because these are declared in a more complicated manner than most other decorators.

I suggest that we get this merged and fix those in subsequent PRs.

mary-poppins · 2018-05-23T17:56:35Z

You can preview 704ab82 at https://pr24000-704ab82.ngbuilds.io/.

mary-poppins · 2018-05-23T18:08:50Z

You can preview d6d73eb at https://pr24000-d6d73eb.ngbuilds.io/.

IgorMinar · 2018-05-23T20:42:46Z

core/Directives (d7426c1)
breadcrumbs missing (1d21ff7)
edit & source code button for individual options (ideally this should also show up for class methods and anything similar to that, but it's ok if this is a separate PR) (9842371)

petebacondarwin · 2018-05-23T20:52:43Z

fail doc-gen if invalid tag is found (requires change to dgeni-packages)

petebacondarwin · 2018-05-23T22:01:21Z

I have cleaned up this PR and added commits for the items that Igor requested above.

mary-poppins · 2018-05-23T22:16:44Z

You can preview 9842371 at https://pr24000-9842371.ngbuilds.io/.

gkalpak

Excited to have the view/edit buttons on members \o/
Not thrilled about how they look (and adding red arrows didn't actually help) 😁 :

gkalpak · 2018-05-24T08:12:47Z

Are .api-section and .api-table used anywhere? I couldn't find any occurrences 😕

weird me neither...

I'm going to delete this and rename the file to styles/2-layout/_api-pages.scss file

gkalpak · 2018-05-24T08:14:52Z

There is no test for this conditional 😱

Under what circumstances can a doc have no corresponding moduleDoc? Do you have an example?

when it is a module? I'll add a test

gkalpak · 2018-05-24T08:17:25Z

Indentation still incorrect 😁

gkalpak · 2018-05-24T08:20:02Z

page-actions might not be a descriptive name any more 😁

renamed to github-links

mary-poppins · 2018-05-25T09:34:33Z

You can preview c065871 at https://pr24000-c065871.ngbuilds.io/.

petebacondarwin · 2018-05-25T09:50:21Z

@gkalpak do you have any suggestions for better styling of the GH links on methods and options?

gkalpak · 2018-05-25T10:12:48Z

I'm no designer 😛

But I would definitely start at centering them vertically:

And I would try out different colors (a dark-ish gray maybe, to make them stand out less):

@sjtrimble will definitely have more useful insights than me 😁

petebacondarwin · 2018-05-25T10:16:01Z

Sounds reasonable. I'll create a new PR after this has merged to try out those ideas.

sjtrimble · 2018-05-25T16:12:19Z

Coming late to the party - is the thought that the main page source and edit would still be there in addition to the 'individual option' ones?

I like @gkalpak idea of having the buttons be more subtle. Would be nice if they turned blue on hover (but without the rounded box border of the current page icons).

Aligning the card header content vertically is as intended in the original design - so that's a go from my perspective :)

petebacondarwin · 2018-06-04T13:43:04Z

@sjtrimble:

is the thought that the main page source and edit would still be there in addition to the 'individual option' ones?

Yes that is correct. The "individual option" ones link to the source for those specific items (e.g. the method), whereas the top level on is for the export as a whole (e.g. the class).

I have centred and coloured the links as suggested.

PTAL

mary-poppins · 2018-06-04T13:54:49Z

You can preview 1b5959c at https://pr24000-1b5959c.ngbuilds.io/.

PR Close #24000

* Code anchors should inherit the font size from their container * Table headings should align with content PR Close #24000

We should not include the package path in the inherited from heading for decorator API docs PR Close #24000

PR Close #24000

This change adds Github edit and view links to methods and decorator options. It is possible to add these to properties also but the UI is rather tight as these are displayed in a table. PR Close #24000

This would cause dangling links since the target, being internal, would not exist in the docs. PR Close #24000

… processor (#24000) We don't really care when this processor runs as long as it happens after the tags have been extracted. By not constraining its `runBefore` property we can ensure that other processors can be run before it. PR Close #24000

…docs (#24000) This commit also factors out `API_CONTAINED_DOC_TYPES` to be used by both `filterContainedDocs` and `addAllowedPropertiesRules`. PR Close #24000

This update allows us to autolink to methods and properties, which means that we can change things like `{@link transition transition()}` to just `transition()`. PR Close #24000

PR Close #24000

This was erroneously committed into master, when it was really only supposed to demo what the pages might look like. PR Close #24000

This commit adds new link disambiguators that mean that more code links can be generated automatically in a sensible way. The best example is the use of properties within class, interface and enum documentation. PR Close #24000

It is cleaner and simpler to use just a straightforward link. PR Close #24000

…4000) PR Close #24000

The overview of the decorator options is now a table. The detailed description of each option is now a full section. PR Close #24000

…24000) The sections such as methods and decorator options are already headed by a H3 heading so we need to map the H3 headings in the API doc source down to H4 headings. This commit includes general heading mapping functionality accessible via the `marked` Nunjucks filter. PR Close #24000

PR Close #24000

#24000) PR Close #24000

This heading is too high for the section because the method name is a H3 but it cannot be a H4 because usage notes may contain H4 headings. PR Close #24000

PR Close #24000

* Code anchors should inherit the font size from their container * Table headings should align with content PR Close #24000

We should not include the package path in the inherited from heading for decorator API docs PR Close #24000

PR Close #24000

This change adds Github edit and view links to methods and decorator options. It is possible to add these to properties also but the UI is rather tight as these are displayed in a table. PR Close #24000

angular-automatic-lock-bot · 2019-09-13T18:20:58Z

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.}

googlebot added the cla: yes label May 18, 2018

petebacondarwin added comp: aio and removed cla: yes labels May 18, 2018

googlebot added the cla: yes label May 18, 2018

petebacondarwin added target: patch This PR is targeted for the next patch release and removed cla: yes labels May 18, 2018

googlebot added the cla: yes label May 18, 2018

petebacondarwin added the action: review The PR is still awaiting reviews from at least one requested reviewer label May 18, 2018

gkalpak suggested changes May 22, 2018

View reviewed changes

petebacondarwin force-pushed the docs-fix-errors-core-2 branch from af721ca to 704ab82 Compare May 23, 2018 17:42

gkalpak approved these changes May 24, 2018

View reviewed changes

petebacondarwin force-pushed the docs-fix-errors-core-2 branch from c065871 to 1b5959c Compare June 4, 2018 13:43

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): fix broken doc-gen unit test (#24000)

facc9d4

PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

fix(aio): tidy up API doc styles (#24000)

840ca05

* Code anchors should inherit the font size from their container * Table headings should align with content PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): fix decorator doc "inherited from" heading (#24000)

1e04df9

We should not include the package path in the inherited from heading for decorator API docs PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): compute breadcrums for all API doc types (#24000)

f43cb93

PR Close #24000

mhevery closed this in 5fb0b56 Jun 13, 2018

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): do not try to auto-link to internal API items (#24000)

131d0d8

This would cause dangling links since the target, being internal, would not exist in the docs. PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): do not allow @usageNotes on properties (#24000)

62443b0

PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): refactor the decorator doc processing (#24000)

d4d8125

PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

docs(aio): remove unused guide doc (#24000)

8977b96

This was erroneously committed into master, when it was really only supposed to demo what the pages might look like. PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

docs: remove unnecessary @linkDocs tags (#24000)

38a0d1f

It is cleaner and simpler to use just a straightforward link. PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): remove unused @linkDocs alias for @link jsdoc tag (#2…

ccb19fe

…4000) PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): rearrange decorator API doc template (#24000)

e371b22

The overview of the decorator options is now a table. The detailed description of each option is now a full section. PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

docs: fix invalid headings (#24000)

e6516b0

PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): rearrange processors to ensure we catch all content errors (

bc4f10c

#24000) PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): remove invalid H3 usage notes heading (#24000)

2b15108

This heading is too high for the section because the method name is a H3 but it cannot be a H4 because usage notes may contain H4 headings. PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): fix broken doc-gen unit test (#24000)

8a4c577

PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

fix(aio): tidy up API doc styles (#24000)

66f6a48

* Code anchors should inherit the font size from their container * Table headings should align with content PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): fix decorator doc "inherited from" heading (#24000)

859a3d5

We should not include the package path in the inherited from heading for decorator API docs PR Close #24000

mhevery pushed a commit that referenced this pull request Jun 13, 2018

build(aio): compute breadcrums for all API doc types (#24000)

8daadf3

PR Close #24000

petebacondarwin deleted the docs-fix-errors-core-2 branch June 14, 2018 10:57

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

Conversation

petebacondarwin commented May 18, 2018

Uh oh!

googlebot commented May 18, 2018

Uh oh!

googlebot commented May 18, 2018

Uh oh!

mary-poppins commented May 18, 2018

Uh oh!

gkalpak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

petebacondarwin commented May 23, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mary-poppins commented May 23, 2018

Uh oh!

mary-poppins commented May 23, 2018

Uh oh!

IgorMinar commented May 23, 2018 • edited by petebacondarwin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

petebacondarwin commented May 23, 2018

Uh oh!

petebacondarwin commented May 23, 2018

Uh oh!

mary-poppins commented May 23, 2018

Uh oh!

gkalpak left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

petebacondarwin May 25, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

petebacondarwin commented May 23, 2018 •

edited

Loading

IgorMinar commented May 23, 2018 •

edited by petebacondarwin

Loading

petebacondarwin May 25, 2018 •

edited

Loading

gkalpak May 24, 2018 •

edited

Loading