docs(docs-infra): Add cross-links to API pages by JeanMeche · Pull Request #57346 · angular/angular

JeanMeche · 2024-08-12T14:50:54Z

This commit adds links to our own symbols in the API pages, including the Code TOC, the description and the Usage notes.

This commit also add the implement/extends symbols for classes & interfaces.

The generation process now logs warnings for links that couldn't not be generated because the symbols can be resolved in the given context.

fixes #57128
fixes #57183
fixes #55571

Worthy examples:

github-actions · 2024-08-12T15:06:15Z

Deployed adev-preview for 8bc381f to: https://ng-dev-previews-fw--pr-angular-angular-57346-adev-prev-ckp3dlh0.web.app

Note: As new commits are pushed to this pull request, this link is updated after the preview is rebuilt.

devversion · 2024-08-14T12:27:29Z

adev/shared-docs/pipeline/api-gen/extraction/index.ts

I think this shows (for the other PR with the core/globals) that we need to maybe have module_name, and a "title" field? I'm worried we are using module_name for more, but then Dev-mode globals breaks

Yes, we'll be able to reuse the logic that I added in #57365

adev/shared-docs/pipeline/api-gen/rendering/entities.ts

devversion · 2024-08-14T12:31:04Z

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

This computation happens for every export. I also wonder, why is this necessary? can you explain? i.e. why do we need to extract the "imported" symbols and returning them as symbols here is a bit ambiguous I feel like.

I've added a comment, let me know if it makes it more clear for you.

devversion · 2024-08-14T12:32:14Z

I like the general approach, but I also don't know how it was done before in the early versions of angular.dev, or why we stopped/reverted the logic, so I will defer to @jelbourn on this for now.

josephperrott · 2024-08-19T16:03:13Z

Deferring to other reviewers for this specific change.

JeanMeche · 2024-08-19T17:17:50Z

Currently trying to reduce the scope of this PR, as it might feel a bit large.
I think the important part are the compiler-cli changes.

jelbourn

I got part of the way through before I need to run for the day, but here's my initial comments

Not sure if you were planning to do this already once you got an okay on the approach, but I'll mention anyway: we should split this change up into more granular commits. In particular:

Separating the symbol collection into its own commit (and this also needs tests)
Changing the representation of class inheritance in its own commit
Minimum necessary changes to the renderer to accomodate any DocEntry structure changes
Further changes to surface the links in the rendered output

packages/compiler-cli/src/ngtsc/docs/src/entities.ts

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

packages/compiler-cli/src/ngtsc/core/src/compiler.ts

packages/compiler-cli/src/ngtsc/docs/src/class_extractor.ts

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

JeanMeche · 2024-08-21T00:10:39Z

I splitted the changes accross multiple commits, I should ease the review of all the changes (or we can spin them off in other PRs)

I'll add the missings tests for the API extraction when I can.

JeanMeche · 2024-08-21T21:07:08Z

adev/shared-docs/pipeline/api-gen/extraction/index.ts

@jelbourn Do you think we should do this concatenation during extraction ?

I don't feel strongly either way

jelbourn

Overall looks good

jelbourn · 2024-08-26T21:49:30Z

adev/shared-docs/pipeline/api-gen/extraction/index.ts

I don't feel strongly either way

jelbourn · 2024-08-26T21:55:48Z

adev/shared-docs/pipeline/api-gen/rendering/transforms/code-transforms.ts

Is this regex valid? When I try it in a couple of different regex visualizers, it fails. Maybe they can't handle this much lookahead?

At the very least it would be good to add a comment that explains the regex at a high level

It is valid, make sure that the visualizer supports ES regex, like https://regex101.com/

devversion

LGTM, great work! Minor comments in the compiler

packages/compiler-cli/src/ngtsc/core/src/compiler.ts

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

devversion · 2024-08-28T12:00:20Z

packages/compiler-cli/src/ngtsc/docs/src/import_extractor.ts

Suggested change

if (moduleSpecifier.startsWith('@angular')) {

if (moduleSpecifier.startsWith('@angular/')) {

would it be better/more generic if we filter everything that is not a relative path?

That would also expose symbols from RxJS, which is not wanted.

It might be the responsibility of the "consumer" of the symbols list to filter out items that cannot be rendered. Or even cooler, we could link to the RxJS docs that way 😄

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

adev/shared-docs/pipeline/api-gen/rendering/symbol-context.ts

adev/shared-docs/pipeline/api-gen/extraction/index.ts

packages/compiler-cli/src/ngtsc/docs/src/extractor.ts

AndrewKushnir · 2024-08-29T14:40:50Z

@JeanMeche there is a conflict with the main branch. Could you please rebase and resolve the merge conflict when you get a chance? Thank you.

This commit changes the structure of the API extraction files to include all symbols used inside a package. The structure is a `Map`, Symbol => package eg: 'ApplicationRef' => '@angular/core'

AndrewKushnir · 2024-08-29T17:50:47Z

Presubmit.

AndrewKushnir · 2024-08-29T20:40:01Z

This PR was merged into the repository by commit 01030d5.

The changes were merged into the following branches: main, 18.2.x

angular-automatic-lock-bot · 2024-09-30T00:11:27Z

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

JeanMeche added the adev: preview label Aug 12, 2024

angular-robot bot added area: docs Related to the documentation area: docs-infra Angular.dev application and infrastructure labels Aug 12, 2024

ngbot bot added this to the Backlog milestone Aug 12, 2024

JeanMeche force-pushed the adev/symbol-links branch 3 times, most recently from 1802547 to bc1710c Compare August 13, 2024 20:57

JeanMeche marked this pull request as ready for review August 13, 2024 21:11

JeanMeche requested a review from devversion August 13, 2024 21:11

pullapprove bot requested a review from crisbeto August 13, 2024 21:11

JeanMeche force-pushed the adev/symbol-links branch from bc1710c to 28c77fd Compare August 13, 2024 21:21

JeanMeche changed the title ~~docs(docs-infra): Add inner links in the API docs entries~~ docs(docs-infra): Add inside links in the API docs entries Aug 13, 2024

JeanMeche changed the title ~~docs(docs-infra): Add inside links in the API docs entries~~ docs(docs-infra): Add links to other symbols in the API docs Aug 13, 2024

devversion reviewed Aug 14, 2024

View reviewed changes

devversion requested a review from jelbourn August 14, 2024 12:32

JeanMeche force-pushed the adev/symbol-links branch 7 times, most recently from f2b9887 to 04769fa Compare August 16, 2024 22:20

JeanMeche changed the title ~~docs(docs-infra): Add links to other symbols in the API docs~~ docs(docs-infra): Add cross-links to API pages Aug 16, 2024

JeanMeche force-pushed the adev/symbol-links branch 5 times, most recently from bbc06cf to 39a8441 Compare August 18, 2024 18:38

JeanMeche force-pushed the adev/symbol-links branch from 7affd47 to 51cb4db Compare August 19, 2024 11:37

JeanMeche requested review from josephperrott and removed request for AndrewKushnir, alxhub and thePunderWoman August 19, 2024 11:37

JeanMeche force-pushed the adev/symbol-links branch 7 times, most recently from 7b52fd0 to 2b0993a Compare August 19, 2024 15:28

josephperrott removed their request for review August 19, 2024 16:02

JeanMeche mentioned this pull request Aug 20, 2024

docs: Add mention to ENVIRONMENT_INITIALIZER #57464

Closed

jelbourn reviewed Aug 20, 2024

View reviewed changes

JeanMeche commented Aug 21, 2024

View reviewed changes

JeanMeche mentioned this pull request Aug 22, 2024

Docs: Additional improvements for the api docs #57492

Closed

jelbourn approved these changes Aug 26, 2024

View reviewed changes

devversion approved these changes Aug 28, 2024

View reviewed changes

JeanMeche added 2 commits August 29, 2024 19:21

refactor(compiler-cli): Add a map of every symbols used inside a package

0867ed6

This commit changes the structure of the API extraction files to include all symbols used inside a package. The structure is a `Map`, Symbol => package eg: 'ApplicationRef' => '@angular/core'

docs(docs-infra): Add support for cross-links on API pages

8bc381f

mvdluit mentioned this pull request Aug 30, 2024

docs (docs-infra): provide links to mentioned API references on API reference detail pages #57128

Closed

JeanMeche mentioned this pull request Aug 30, 2024

refactor(compiler-cli): Do not extract symbols from private modules. #57611

Closed

	if (moduleSpecifier.startsWith('@angular')) {
	if (moduleSpecifier.startsWith('@angular/')) {

Conversation

JeanMeche commented Aug 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devversion commented Aug 14, 2024

Uh oh!

josephperrott commented Aug 19, 2024

Uh oh!

JeanMeche commented Aug 19, 2024

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JeanMeche commented Aug 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jelbourn 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!

devversion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AndrewKushnir commented Aug 29, 2024

Uh oh!

AndrewKushnir commented Aug 29, 2024

Uh oh!

AndrewKushnir commented Aug 29, 2024

Uh oh!

angular-automatic-lock-bot bot commented Sep 30, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

JeanMeche commented Aug 12, 2024 •

edited

Loading

github-actions bot commented Aug 12, 2024 •

edited

Loading

JeanMeche commented Aug 21, 2024 •

edited

Loading