chore: add api-docs package #9803
Conversation
| function sanitizeDescription(description: string) { | ||
| // Fix links to other elements | ||
| description = description.replace(/#\/elements\//gu, '/elements/'); | ||
| // Fix links to properties (e.g. #property-dataProvider to #dataprovider) |
There was a problem hiding this comment.
Document fragments might need some work, I think there are some duplicates on some pages at the moment. Could be improved later IMO, would require figuring out how to customize these in Astro from within the Markdown file.
There was a problem hiding this comment.
You mean such duplicates? Or is it a different issue?
There was a problem hiding this comment.
All headings in the document are linkable with a document fragment (e.g. #selected-item). For those there can be duplicates. For example the GridPro page has a heading for the dataProvider property, and then there is a heading for the DataProvider type. If some other page would link to one of those headings you might not end up at the correct one. Doesn't seem to be a problem at the moment though.
There was a problem hiding this comment.
For the record, the new 11ty based version handles this by changing the second heading to #dataprovider-1.
| } | ||
|
|
||
| // Properties | ||
| const publicProperties = filterPublicApi(element.properties); |
There was a problem hiding this comment.
The new API docs only show public APIs.
| "build": "astro build", | ||
| "preview": "astro preview", | ||
| "astro": "astro", | ||
| "generate": "tsx generate.ts" |
There was a problem hiding this comment.
Used tsx for now. Since Node 23 this works without, but we don't have that on CI servers yet.
There was a problem hiding this comment.
This customizes the default page header to have buttons / links for the Markdown content.
api-docs/src/content.config.ts
Outdated
| loader: docsLoader(), | ||
| schema: docsSchema({ | ||
| extend: z.object({ | ||
| pageType: z.optional(z.string()), |
There was a problem hiding this comment.
Customizes the page schema to add pageType. This is used to only render the Markdown button / links on element pages, but not on the index page.
api-docs/types.ts
Outdated
There was a problem hiding this comment.
This implements the type lookup from the TS declaration files.
There was a problem hiding this comment.
This generates the content for the Astro site based on analysis.json.
|
On some pages, there are duplicate event names that differ only by a hyphen, for example: http://localhost:4321/elements/vaadin-app-layout/ |
0c2f8a6 to
74fd771
Compare
For some reason I added generation of property change events, I could have sworn some were missing from the JSON. But after double-checking that doesn't seem to be the case. So I removed that part of the generator. Looks like the number of events now line up between old and new API docs. |
f0f451b to
22193f9
Compare
|
Description
Adds an Astro-based API docs website that is intended to replace the current
iron-docs-viewerbased one at some point.Compared to the current one, it has the following benefits:
Type of change