Docs: Generate proper markdown heading for API docs (enabling automatic "Table of Contents" for API pages)

[juanmaguitar]

What problem does this address?

In the automatic generated DOCS for API details ( for example: https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/data/data-core.md ) the elements being documented (such as methods, selectors, action creators and so) are being generated as links and not as headings (with proper level)

# WordPress Core Data
Namespace: `core`.
## Selectors
<!-- START TOKEN(Autogenerated selectors|../../../../packages/core-data/src/selectors.js) -->
<a name="canUser" href="#canUser">#</a> **canUser**
Returns whether the current user can perform the given action on the given
REST resource.
Calling this may trigger an OPTIONS request to the REST API via the
`canUser()` resolver.

This final markup doesn't allow to generate automatic Table of Contents for each page (with tools such as markdown-toc)

What is your proposed solution?

In general, I think having Table of Contents sections in these API’s pages would help people to process and access the information in

I think having these links generated as proper headings levels for each item being documented (each selector in this case) would result in a more correct markdown while also enabling automatically generated Table of Contents for each API page

[juanmaguitar]

The file in charge of orchestrating this transformation seems to be bin/api-docs/update-api-docs.js that internally uses the @wordpress/docgen package

[juanmaguitar]

I think this issue is related with #14341

[oandregal]

I think this change should be fine: it doesn't hurt to try, we can always revert if the result is not adequate.

For context, I presume we used links to allow adding links to the code, which we did at the beginning, and also to make the declarations bookmarkable in the three environments the docs are rendered: the block editor handbook, GitHub, and the npm packages. I've just checked and both the block editor handbook and GitHub auto-generate links to the headings, so having specific links is no longer necessary. npm doesn't but also the existing links don't work as bookmarks due to how npm parses the README file of packages.