docs(docs-infra): fix missing code examples in the API reference by hawkgs · Pull Request #59004 · angular/angular

hawkgs · 2024-12-02T10:35:03Z

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting, local variables)
Refactoring (no functional changes, no api changes)
Build related changes
CI related changes
Documentation content changes
angular.dev application / infrastructure changes
Other... Please describe:

What is the current behavior?

Issue Number: #56321

What is the new behavior?

The new examples extraction and interpolation mechanism is integrated into the API gen JSON extraction phase since I thought that it makes most sense given the JSON files could be potentially consumed by other services and having the examples already inlined is desired. Let me know, if that's good. Currently, all {@example}-s are being targeted by the script and then replaced with the respective code example wrapped in a Markdown code block.

The extractor/parser supports various #docregion use variations that can be checked in the unit tests. It is still possible that I missed a use case but these are based on the different examples that I explored during the implementation.

It is important to note that there are about half a dozen examples that are still missing because of the <code-example> usage. Some of the instances have already been replaced with {@example} – those that have only a region parameter (a63b524). The remaining instances are left because they contain a header param. All that being said, I want to start a discussion in that regard – should we get rid of <code-example> completely in favor of {@example} or vice versa? Obviously, there are other details that have to be taken into account like whether the output of this interpolation mechanism should produce Markdown or HTML but this is something that can be decided as a secondary thing.

Does this PR introduce a breaking change?

Yes
No

The code examples in `package/examples` are now passed to the API JSON generator.

The script substitutes the JSDoc example tags with the respective code sample.

Add support for nested #docregion-s and modify the examples caching.

It seems that there are overlapping region markers and an example can be composed by multiple regions.

…amples The transform is no longer relevant nor it served any functional purpose.

…ile types Set the code block language highlighting based on the file type.

Setup the test suite and add the initial test.

Minor bug fixes found and implemented during testing.

Test all use cases that are supported by the interpolation mechanism.

@example-s

…ram to @example-s Replace all <code-example>-s within TS files that contain only a path and a region with JSDoc @example-s.

github-actions · 2024-12-02T15:20:28Z

Deployed adev-preview for 88b4fc6 to: https://ng-dev-previews-fw--pr-angular-angular-59004-adev-prev-7icqucjj.web.app

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

Add missing file header comments and update others.

Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`.

josephperrott

LGTM

josephperrott

LGTM

Reviewed-for: global-approvers

Add missing file header comments and update others. PR Close #59004

…59004) Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`. PR Close #59004

The script substitutes the JSDoc example tags with the respective code sample. PR Close #59004

Add support for nested #docregion-s and modify the examples caching. PR Close #59004

…#59004) It seems that there are overlapping region markers and an example can be composed by multiple regions. PR Close #59004

…amples (#59004) The transform is no longer relevant nor it served any functional purpose. PR Close #59004

…ile types (#59004) Set the code block language highlighting based on the file type. PR Close #59004

Setup the test suite and add the initial test. PR Close #59004

Minor bug fixes found and implemented during testing. PR Close #59004

Test all use cases that are supported by the interpolation mechanism. PR Close #59004

@example-s

…ram to @example-s (#59004) Replace all <code-example>-s within TS files that contain only a path and a region with JSDoc @example-s. PR Close #59004

Add missing file header comments and update others. PR Close #59004

…59004) Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`. PR Close #59004

angular-automatic-lock-bot · 2025-01-04T00:11:21Z

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

…#59004) The code examples in `package/examples` are now passed to the API JSON generator. PR Close angular#59004

The script substitutes the JSDoc example tags with the respective code sample. PR Close angular#59004

Add support for nested #docregion-s and modify the examples caching. PR Close angular#59004

…angular#59004) It seems that there are overlapping region markers and an example can be composed by multiple regions. PR Close angular#59004

…amples (angular#59004) The transform is no longer relevant nor it served any functional purpose. PR Close angular#59004

…ile types (angular#59004) Set the code block language highlighting based on the file type. PR Close angular#59004

Setup the test suite and add the initial test. PR Close angular#59004

Minor bug fixes found and implemented during testing. PR Close angular#59004

Test all use cases that are supported by the interpolation mechanism. PR Close angular#59004

@example-s

…ram to @example-s (angular#59004) Replace all <code-example>-s within TS files that contain only a path and a region with JSDoc @example-s. PR Close angular#59004

Add missing file header comments and update others. PR Close angular#59004

…ngular#59004) Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`. PR Close angular#59004

hawkgs added 10 commits November 28, 2024 14:19

feat(docs-infra): include code examples files in the API gen

4db51ca

The code examples in `package/examples` are now passed to the API JSON generator.

feat(docs-infra): implement interpolation script

b7ef8b5

The script substitutes the JSDoc example tags with the respective code sample.

fix(docs-infra): interpolation script nesting

25ee2ed

Add support for nested #docregion-s and modify the examples caching.

fix(docs-infra): handle regions overlap and multiple-regions examples

8715809

It seems that there are overlapping region markers and an example can be composed by multiple regions.

feat(docs-infra): remove redundant JSDoc transform related to code ex…

7cbfe58

…amples The transform is no longer relevant nor it served any functional purpose.

fix(docs-infra): markdown code block highlighting for the different f…

16828a4

…ile types Set the code block language highlighting based on the file type.

test(docs-infra): add initial test

160366a

Setup the test suite and add the initial test.

fix(docs-infra): minor bug fixes

f7dce6e

Minor bug fixes found and implemented during testing.

test(docs-infra): interpolation mechanism

c51ee19

Test all use cases that are supported by the interpolation mechanism.

refactor(docs-infra): convert code-example-s that have only region pa…

a63b524

…ram to @example-s Replace all <code-example>-s within TS files that contain only a path and a region with JSDoc @example-s.

pullapprove bot requested review from AndrewKushnir, alxhub, crisbeto and devversion December 2, 2024 10:35

angular-robot bot added detected: feature PR contains a feature commit area: docs-infra Angular.dev application and infrastructure labels Dec 2, 2024

ngbot bot added this to the Backlog milestone Dec 2, 2024

JeanMeche added the adev: preview label Dec 2, 2024

refactor(docs-infra): update comments

f9a42bf

Add missing file header comments and update others.

hawkgs force-pushed the docs/fix-code-examples branch from 51029a8 to f9a42bf Compare December 3, 2024 08:41

pullapprove bot requested review from josephperrott and removed request for devversion December 3, 2024 08:41

feat(docs-infra): use angular-ts and angular-html shiki highlighting

88b4fc6

Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`.

josephperrott approved these changes Dec 4, 2024

View reviewed changes

josephperrott added action: merge The PR is ready for merge by the caretaker target: patch This PR is targeted for the next patch release labels Dec 4, 2024

josephperrott removed request for AndrewKushnir and alxhub December 4, 2024 15:16

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

refactor(docs-infra): update comments (#59004)

e18adff

Add missing file header comments and update others. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

feat(docs-infra): use angular-ts and angular-html shiki highlighting (#…

7ad1f27

…59004) Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`. PR Close #59004

pkozlowski-opensource closed this in a4ee2d9 Dec 4, 2024

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

feat(docs-infra): implement interpolation script (#59004)

8b93e3c

The script substitutes the JSDoc example tags with the respective code sample. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

fix(docs-infra): interpolation script nesting (#59004)

e0beb27

Add support for nested #docregion-s and modify the examples caching. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

feat(docs-infra): remove redundant JSDoc transform related to code ex…

f13f52f

…amples (#59004) The transform is no longer relevant nor it served any functional purpose. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

fix(docs-infra): markdown code block highlighting for the different f…

9ca8ddb

…ile types (#59004) Set the code block language highlighting based on the file type. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

test(docs-infra): add initial test (#59004)

b97b920

Setup the test suite and add the initial test. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

fix(docs-infra): minor bug fixes (#59004)

d40967c

Minor bug fixes found and implemented during testing. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

test(docs-infra): interpolation mechanism (#59004)

c13528b

Test all use cases that are supported by the interpolation mechanism. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

refactor(docs-infra): update comments (#59004)

0a399e7

Add missing file header comments and update others. PR Close #59004

pkozlowski-opensource pushed a commit that referenced this pull request Dec 4, 2024

feat(docs-infra): use angular-ts and angular-html shiki highlighting (#…

77a0ee8

…59004) Use `angular-ts` instead of `typescript` and `angular-html` instead of `html`. PR Close #59004

angular-automatic-lock-bot bot locked and limited conversation to collaborators Jan 4, 2025

hawkgs deleted the docs/fix-code-examples branch January 4, 2025 15:06

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

feat(docs-infra): include code examples files in the API gen (angular…

a45d926

…#59004) The code examples in `package/examples` are now passed to the API JSON generator. PR Close angular#59004

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

feat(docs-infra): implement interpolation script (angular#59004)

02a1fcb

The script substitutes the JSDoc example tags with the respective code sample. PR Close angular#59004

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

fix(docs-infra): interpolation script nesting (angular#59004)

ac13db3

Add support for nested #docregion-s and modify the examples caching. PR Close angular#59004

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

test(docs-infra): add initial test (angular#59004)

c7ea2bd

Setup the test suite and add the initial test. PR Close angular#59004

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

fix(docs-infra): minor bug fixes (angular#59004)

da0ace9

Minor bug fixes found and implemented during testing. PR Close angular#59004

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

test(docs-infra): interpolation mechanism (angular#59004)

4e5a521

Test all use cases that are supported by the interpolation mechanism. PR Close angular#59004

PrajaktaB27 pushed a commit to PrajaktaB27/angular that referenced this pull request Feb 7, 2025

refactor(docs-infra): update comments (angular#59004)

8b46842

Add missing file header comments and update others. PR Close angular#59004

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(docs-infra): fix missing code examples in the API reference#59004

docs(docs-infra): fix missing code examples in the API reference#59004
hawkgs wants to merge 12 commits intoangular:mainfrom
hawkgs:docs/fix-code-examples

hawkgs commented Dec 2, 2024 •

edited

Loading

Uh oh!

github-actions bot commented Dec 2, 2024 •

edited

Loading

Uh oh!

josephperrott left a comment

Uh oh!

josephperrott left a comment

Uh oh!

angular-automatic-lock-bot bot commented Jan 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

hawkgs commented Dec 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Uh oh!

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

Uh oh!

Uh oh!

josephperrott left a comment

Choose a reason for hiding this comment

Uh oh!

josephperrott left a comment

Choose a reason for hiding this comment

Uh oh!

angular-automatic-lock-bot bot commented Jan 4, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hawkgs commented Dec 2, 2024 •

edited

Loading

github-actions bot commented Dec 2, 2024 •

edited

Loading