feat: docs

[valgaze]

Proof of concept for auto-gen'd docs in markdown, demo here

• bun run docs to generate types then generate docs based on types in directory api-docs

• Uses typedoc to focus contributor doc energy on high-value content rather than manually annotating + updating types & parameters

• Use typedoc.json's publicPath field to set base path for URLs (otherwise falls back to relative prefixed with commit)

• duplicative tsconfig.docs.json variant since extends appears to be in-flight

• (not sure) optional "images" folder for embedding fun bun logo or gif, ex ![desc](media://bun.png)

Without publicPath links in repo to specific code appear to have a pathing issue

[xHyroM]

Why npm: scripts?

[valgaze]

@xHyroM Fun for benchmark

[xHyroM]

Probably remove it, we don't need to have benchmark for generating docs

[xHyroM]

Why api-docs folder is in .gitignore?

[valgaze]

@xHyroM wasn't sure whether many files would make noisy source control-- I'll add to this PR

[xHyroM]

resolve conflicts

[Jarred-Sumner]

This is nice. Can we put all of them into a single file and into the readme of this repository below "Contributing"? The goal is so you can CMD + F easily to search all of bun's types at once

[valgaze]

@xHyroM -- deconflicted

@Jarred-Sumner -- There's too much data for a renderable README-- using concat-md I was getting ~6mb's and it'll probably grow over time right?

ex.

W/ this Typedoc appraoch, maybe a compromise would be to concat the module.md that gets generated. That way you could have a renderable readme and still get the CTRL-f search'y experience

ex. https://gist.github.com/valgaze/04dde2c997c016e0640256afb616b23d

To pull off you could do something like the following:

• README_top.md: Top "static" template the README,

• Concat README.top w/ api-docs/modules.md into README

{
    "special_script": "bun run docs && cp README_top.md README.md && cat api-docs/modules.md >> README.md"
}

[xHyroM]

Or we can turn on GitHub pages with Jekyll theme (for now)

[paperdave]

i looked at the demo linked at the top:

is this intentional that it points to the bundled types as well as the source?

[xHyroM]

• can you resolve conflicts?

[valgaze]

@xHyroM deconflicted

[xHyroM]

@xHyroM deconflicted

@valgaze Can you exclude dist/types.d.ts ?

[xHyroM]

After removing https://github.com/valgaze/bun-types/blob/3f77af99bef82d463fe7b847fb3448134748c6a3/package.json#L21 , ping me and I'll merge this

[xHyroM]

@valgaze

[valgaze]

@xHyroM Alright sorted-- once merged the publicPath url's in the docs should resolve properly

[xHyroM]

Okay, thanks