docs: remove deprecated methods from API docs

[Kartikayy007]

Description

Type: Bug Fix

Fixes broken TOC link for deprecated method generator.generateFromString by filtering deprecated methods from generated API documentation.

Problem:

• Deprecated methods appeared in TOC with strikethrough (~~text~~)
• The ~ character broke URL anchors (e.g., #~~generatorgeneratefromstring~~)
• Users couldn't navigate to deprecated method documentation

Solution:

• Created 3 custom Handlebars templates to filter methods marked with @deprecated
  • member-index-list.hbs - Filters list-format TOC
  • member-index-grouped.hbs - Filters grouped-format TOC (used by Generator class)
  • members.hbs - Filters documentation content
• Updated package.json docs script to use new templates
• Added HTML post-processing to fix MDX parser compatibility
• Regenerated api.md without deprecated methods

Ref: #1755 (comment)

Result:

• No broken links (deprecated methods completely removed)
• Cleaner documentation (users don't see outdated APIs)
• Future-proof (any @deprecated method automatically filtered)

Testing:

cd apps/generator
npm run docs
grep "generateFromString" docs/api.md  # no results = success

screen recording

screen_compressed.mp4

Resolves #1634

[changeset-bot]

⚠️ No Changeset found

Latest commit: c184eb0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[asyncapi-bot]

What reviewer looks at during PR review

The following are ideal points maintainers look for during review. Reviewing these points yourself beforehand can help streamline the review process and reduce time to merge.

1. PR Title: Use a concise title that follows our Conventional Commits guidelines and clearly summarizes the change using imperative mood (it means spoken or written as if giving a command or instruction, like "add new helper for listing operations")

   Note - In Generator, prepend feat: or fix: in PR title only when PATCH/MINOR release must be triggered.

2. PR Description: Clearly explain the issue being solved, summarize the changes made, and mention the related issue.

   Note - In Generator, we use Maintainers Work board to track progress. Ensure the PR Description includes Resolves #<issue-number> or Fixes #<issue-number> this will automatically close the linked issue when the PR is merged and helps automate the maintainers workflow.

3. Documentation: Update the relevant Generator documentation to accurately reflect the changes introduced in the PR, ensuring users and contributors have up-to-date guidance.

4. Comments and JSDoc: Write clear and consistent JSDoc comments for functions, including parameter types, return values, and error conditions, so others can easily understand and use the code.

5. DRY Code: Ensure the code follows the Don't Repeat Yourself principle. Look out for duplicate logic that can be reused.

6. Test Coverage: Ensure the new code is well-tested with meaningful test cases that pass consistently and cover all relevant edge cases.

7. Commit History: Contributors should avoid force-pushing as much as possible. It makes it harder to track incremental changes and review the latest updates.

8. Template Design Principles Alignment: While reviewing template-related changes in the packages/ directory, ensure they align with the Assumptions and Principles. If any principle feels outdated or no longer applicable, start a discussion these principles are meant to evolve with the project.

9. Reduce Scope When Needed: If an issue or PR feels too large or complex, consider splitting it and creating follow-up issues. Smaller, focused PRs are easier to review and merge.

10. Bot Comments: As reviewers, check that contributors have appropriately addressed comments or suggestions made by automated bots. If there are bot comments the reviewer disagrees with, react to them or mark them as resolved, so the review history remains clear and accurate.

[coderabbitai]

Walkthrough

Adds three Handlebars templates for member indexing (grouped and list) plus a children wrapper, updates the docs generation script to include them (removing the prior docs.hbs partial), and deletes the Generator.generateFromString entry from the generated API docs.

Changes

Cohort / File(s)	Summary
New grouped member template apps/generator/docs/jsdoc2md-handlebars/member-index-grouped.hbs	New partial that skips deprecated items, renders indented/grouped member index bullets, uses _title or a signature link, and recursively invokes itself with an incremented baseLevel for nested groups.
New list-style member template apps/generator/docs/jsdoc2md-handlebars/member-index-list.hbs	New partial that omits deprecated items, renders a sig-link-parent with indentation, and recursively renders member-index-list for indexChildren to produce nested, indented lists.
Children/docs wrapper apps/generator/docs/jsdoc2md-handlebars/members.hbs	New template that renders child items with inherited filtering undefined and conditionally renders the docs partial only for non-deprecated items; includes whitespace control.
Docs generation script update apps/generator/package.json	docs script updated: removed docs/jsdoc2md-handlebars/docs.hbs and added the three new partials (member-index-list.hbs, member-index-grouped.hbs, members.hbs) in the jsdoc2md --partial ... invocation; output redirection unchanged.
Generated API docs apps/generator/docs/api.md	Removed the Generator.generateFromString method entry and its deprecated section from the generated API documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify Handlebars syntax, partial names, and correct usage of ~ whitespace markers.
• Validate recursive partial invocations and baseLevel arithmetic for indentation.
• Confirm deprecation checks reliably skip deprecated items (relevant to the TOC/link issue for generateFromString).
• Review package.json docs script for correct partial ordering and paths.
• Inspect apps/generator/docs/api.md removal to ensure no remaining broken TOC links.

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR successfully addresses issue #1634 by filtering deprecated methods from TOC and content via three Handlebars template modifications wrapped with {{#unless deprecated}}, preventing broken anchors with tilde characters.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing issue #1634: template modifications to filter deprecated methods, package.json script updates to include new templates, and regenerated API documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The PR title accurately describes the main change: removing deprecated methods from API docs by modifying Handlebars templates and regenerating documentation.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[derberg]

description of PR doesn't match the changes

also please provide:

• original handlebars as comment for review of things that changed
• explain why 3 handlebars had to be modified, which parts exactly and why

[Kartikayy007]

All changes follow the same idea that is to wrap existing logic with {{#unless deprecated}} to skip deprecated methods.

Template 1: member-index-list.hbs

Original (node_modules/dmd/partials/all-docs/docs/member-index/member-index-list.hbs):

{{>index-indent}}* {{>sig-link-parent}}
{{#indexChildren ~}}
{{>member-index-list~}}
{{/indexChildren}}

Modified:

{{#unless deprecated}}
{{>index-indent}}* {{>sig-link-parent}}
{{#indexChildren ~}}
{{>member-index-list~}}
{{/indexChildren}}
{{/unless}}

and this is to filters deprecated methods from list-format TOC.

---

Template 2: member-index-grouped.hbs

Original (node_modules/dmd/partials/all-docs/docs/member-index/member-index-grouped.hbs):

{{string-repeat "    " (add level baseLevel)}}* {{#unless (equal _title undefined)}}_{{_title}}_{{else}}{{>sig-link}}{{/unless}}
{{#groupBy (option "group-by")~}}
{{>member-index-grouped baseLevel=(add ../level ../baseLevel 1)~}}
{{/groupBy~}}

Modified:

{{#unless deprecated}}
{{string-repeat "    " (add level baseLevel)}}* {{#unless (equal _title undefined)}}_{{_title}}_{{else}}{{>sig-link}}{{/unless}}
{{#groupBy (option "group-by")~}}
{{>member-index-grouped baseLevel=(add ../level ../baseLevel 1)~}}
{{/groupBy~}}
{{/unless}}

Why: Generator class uses grouped TOC format. Template 1 alone will not fix this.

---

Template 3: members.hbs

Original (node_modules/dmd/partials/all-docs/docs/members.hbs):

{{#children inherited=undefined ~}}
{{>docs~}}
{{/children~}}

Modified:

{{#children inherited=undefined ~}}
{{#unless deprecated}}
{{>docs~}}
{{/unless}}
{{/children~}}

Why: Removes deprecated method documentation content. Without this, the full docs section would be there even though TOC links are removed.

---

• Templates 1 & 2: Remove from TOC (two different format styles)
• Template 3: Remove documentation content

Without all 3:
either broken TOC links or orphaned documentation sections.

---

Before: ~~[.generateFromString(...)]~~ → broken link
After: Method completely removed → no broken links

[asyncapi-bot]

🚀 Docs preview deployed
Below link points directly to the generator docs preview. May the force be with you!
→ https://691aa0dc679a90699107d60c--asyncapi-website.netlify.app/docs/tools/generator

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[asyncapi-bot]

🚀 Docs preview deployed
Below link points directly to the generator docs preview. May the force be with you!
→ https://691aac44c4ab620eec8f1dd3--asyncapi-website.netlify.app/docs/tools/generator

[Kartikayy007]

description of PR doesn't match the changes

also please provide:

• original handlebars as comment for review of things that changed
• explain why 3 handlebars had to be modified, which parts exactly and why

I've updated it more descriptive while being to the point. However, earlier coderabbit automatically generated a misleading summary at the bottom that characterises this as an "enhancement" with "new organisational templates," when it's actually a straightforward bug fix that filters out deprecated methods to resolve broken links.

please see: https://691aac44c4ab620eec8f1dd3--asyncapi-website.netlify.app/docs/tools/generator/api

[derberg]

lgtm, I like the approach, removing deprecated from docs is also good

[derberg]

/rtm