docs(headless): api-extractor doc generation PoC #476
Conversation
samisayegh
requested review from
btaillon-coveo,
nrawji,
olamothe and
ThibodeauJF
as code owners
| type: string; | ||
| isOptional: boolean; | ||
| desc: string; | ||
| // notes?: [] |
There was a problem hiding this comment.
This property would be to include things like default, min, max, beta etc. I did not support it for the PoC.
There was a problem hiding this comment.
You mean when we annotate @default 5 in the JSDoc, it would be "leveraged" by notes ?
How would that be leveraged exactly ?
There was a problem hiding this comment.
Yes, this script should ultimately include the tags and their values as part of the parsed object and the outputed JSON. From there, the ruby scripts and templates inside the jekyll doc repo would be free to represent the information as they wish, whether in a table or some other structure.
| @@ -16,15 +16,18 @@ | |||
| "scripts": { | |||
| "start": "npx concurrently \"npm run typedefinitions -- -w\" \"rollup -c -w\"", | |||
| "build": "npm run clean && npm run build:prod", | |||
| "build:prod": "rollup -c --environment BUILD:production && npm run typedefinitions", | |||
| "build:prod": "npm run typedefinitions && rollup -c --environment BUILD:production", | |||
There was a problem hiding this comment.
Typedefinitions are generate before the rollup step to resolve import types.
There was a problem hiding this comment.
This looks solid to me. We'll need to do some processing on the desc field, but it seems to contain everything we need. I also think testing it on the Facet controllers before we get too deep into this strategy would be worthwhile, since that's a main sticking point at the moment.
| @@ -57,20 +57,57 @@ const initialStateSchema = new Schema({ | |||
| page: new NumberValue({min: 1}), | |||
| }); | |||
|
|
|||
| export type Pager = ReturnType<typeof buildPager>; | |||
| export interface Pager { | |||
There was a problem hiding this comment.
The mass interface edit is certainly gonna be painful but if it's necessary 🤷♂️
There was a problem hiding this comment.
How does it affect intellisense in vscode ?
Is there any major difference, or is it essentially the same ?
There was a problem hiding this comment.
The intellisense is identical.
Ideally, I would have liked to keep the freedom to use any of typescript's features, but the ts compiler is ahead of the documentation tools atm, which are either unable to resolve the documentation (e.g. api-extractor) or resolve the documentation but output a JSON with all the intermediate steps (typedoc).
There was a problem hiding this comment.
I guess it's more a question for @kaitlynkatz , but when this is merged, this would most probably break some system in the documentation website, right ?
Any coordination that needs to happen between the two ?
| type: string; | ||
| isOptional: boolean; | ||
| desc: string; | ||
| // notes?: [] |
There was a problem hiding this comment.
You mean when we annotate @default 5 in the JSDoc, it would be "leveraged" by notes ?
How would that be leveraged exactly ?
| @@ -57,20 +57,57 @@ const initialStateSchema = new Schema({ | |||
| page: new NumberValue({min: 1}), | |||
| }); | |||
|
|
|||
| export type Pager = ReturnType<typeof buildPager>; | |||
| export interface Pager { | |||
There was a problem hiding this comment.
How does it affect intellisense in vscode ?
Is there any major difference, or is it essentially the same ?
Indeed, this is an area to dig into. The JSON parser actually parses the tsdoc into a tree of nodes, making it possible to retrieve sections such as
Yep, I will tackle the regular Facet next, |
|
Pull Request Report PR Title ✅ Title follows the conventional commit spec. Bundle Size
|
This PR shows a proof-of-concept for generating documentation for the Pager controller. I checked in the final JSON to help visualize the output of the parsing step.
General
I found api-extractor easier to work with compared to typedoc. It's a tool that is focused on our exact use-case (i.e. extracting documentation to present in a custom template). The JSON was easier to navigate. There is also a parser for the JSON that made post-processing much easier. Not needing to write a parser allows us to benefit from the project over time as the team at Microsoft develops it.
One draw-back was api-extractor cannot extract docs from inside a controller, or on types. This means we have to use interfaces and write out the properties. We cannot use typescript inference (e.g. type Pager = ReturnType). One positive is it makes post-processing simpler. Typedoc was able to extract everything, it generated a JSON was complex to parse. One negative is there will be repetition of doc strings for certain controllers (e.g. facets, search-box/standalone search-box).
Notes
import()types that api-extractor cannot parse. There is an open issue ([api-extractor] import() types are not handled correctly in .d.ts rollups microsoft/rushstack#1050) to add support, but until this happens, we need this additional step.AbortControllerandResponse.