Migrate the project to TypeScript #61
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
adamziel
added
[Type] Documentation
adamziel
force-pushed
the
typescript/migrate
branch
2 times, most recently
from
70ba935 to
69f970c
Compare
The major reason is that JavaScript documentation tools are severely lacking and they don't even support the modern JavaScript syntax. TypeScript is well supported, and the official tsdoc project provides tools to generate the api model from the codebase. From there, generating a markdown reference is just a templating problem. Documentatino aside, this brings the type safety, enables static checks, and gives us autocompletion for free.
adamziel
force-pushed
the
typescript/migrate
branch
from
69f970c to
efa8bbe
Compare
Merged
adamziel
added a commit
that referenced
this pull request
Nov 5, 2022
## Overview Adds a API documentation pipeline: 1. Build TypeScript types using `tsc` 2. Generate an API model and store it as JSON using `api-extractor` from the [TSDoc toolkit](https://tsdoc.org/) 3. Generate markdown files from the API model using a **highly** customized version of TSDoc's api-extractor I put in the `typescript-reference-doc-generator` package. 4. Generate a pretty HTML page from the markdown using Vitepress (it's likely to change to another tool) I'll merge the documentation itself in another PR. Technically, you run these commands: ``` npm run build:api-docs npm run dev:docs:server ``` And get this page: <img width="1125" alt="CleanShot 2022-11-04 at 22 11 57@2x" src="https://user-images.githubusercontent.com/205419/200110405-b4bc130f-50cd-432d-a09d-93a6f10e05d8.png"> <img width="1134" alt="CleanShot 2022-11-04 at 22 11 41@2x" src="https://user-images.githubusercontent.com/205419/200110401-22740c94-cd5b-42e6-96c6-e77724a10908.png"> Follows up on #61
adamziel
added a commit
that referenced
this pull request
Nov 7, 2022
Pookie717
added a commit
to Pookie717/wordpress-playground
that referenced
this pull request
Oct 1, 2023
## Overview Adds a API documentation pipeline: 1. Build TypeScript types using `tsc` 2. Generate an API model and store it as JSON using `api-extractor` from the [TSDoc toolkit](https://tsdoc.org/) 3. Generate markdown files from the API model using a **highly** customized version of TSDoc's api-extractor I put in the `typescript-reference-doc-generator` package. 4. Generate a pretty HTML page from the markdown using Vitepress (it's likely to change to another tool) I'll merge the documentation itself in another PR. Technically, you run these commands: ``` npm run build:api-docs npm run dev:docs:server ``` And get this page: <img width="1125" alt="CleanShot 2022-11-04 at 22 11 57@2x" src="https://user-images.githubusercontent.com/205419/200110405-b4bc130f-50cd-432d-a09d-93a6f10e05d8.png"> <img width="1134" alt="CleanShot 2022-11-04 at 22 11 41@2x" src="https://user-images.githubusercontent.com/205419/200110401-22740c94-cd5b-42e6-96c6-e77724a10908.png"> Follows up on WordPress/wordpress-playground#61
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Descriptions
TypeScript has excellent documentation tools. JavaScript doesn't.
I've tried to generate an API reference documentation from the JavaScript code. All the tools I've tried were either lacking, outdated, abandoned, or they didn't support the modern JavaScript syntax.
TypeScript's official TSdoc toolkit is capable of generating an api data model from the codebase. From there, building a markdown reference is just a templating problem.
Documentation aside, this brings the type safety, enables static checks, and gives us autocompletion for free.