docs: create docs and wiki

[nberlette]

Docs and Wiki

This is a tracking issue for an upcoming PR that will add both a documentation
section (./docs) and a GitHub Wiki to the project. The wiki will be located at
the dedicated ./wiki page (which is technically its own repository), and
linked in the main repo as a submodule pointing to the ./wiki directory.

Auto-Generation

All documentation will be generated automatically using a custom program I've
developed which runs on Deno's built-in deno doc command. All docs and wiki
content is generated purely from the source code and its JSDoc comments; as
such, it's paramount that all code is fully documented with explicit types.

GitHub Pages (./docs)

The ./docs directory will be used to generate a static site for GitHub Pages.

VitePress

Initially I was simply going to use jekyll (GitHub's default static site tool),
but I've decided to use VitePress instead, for a more modern and visually
appealing output. Furthermore, VitePress supports custom themes and plugins,
which allows me to create a more tailored experience for the project.

Twoslash + Shiki

The primary addition will be twoslash support in all code examples and also
the function signatures. This will allow users to hover over code examples,
return types, and identifiers to see complete and accurate type information
displayed in a rich format. All within the documentation itself.

This can be achieved by using the shiki syntax highlighter, which is built-in
to the VitePress documentation generator. The specific package used to add the
twoslash support is @shikijs/twoslash.

GitHub Wiki (./wiki)

All the same documentation available in the ./docs directory will also be
available in the GitHub Wiki, but in a straightforward, pure markdown format.

This will allow users to easily view the documentation in a more traditional
format, right on the GitHub site, without needing to visit the static site.

Note

I may also configure the doc generator tool to output additional content,
examples, and other details that may not be included in the static site.

On the flip side, I may also choose to do the opposite, and include less
content in the wiki, and more in the static site. This is still to be
determined, and I'll probably make that decision based on user feedback.

---

Roadmap and Plans

• use deno doc's webassembly build to generate doc nodes.
  • fallback to the CLI version if needed
• support custom templates ([vento]) for rendering
• add a --readme mode to keep the README up-to-date with the code.
• add a --wiki mode to generate the GitHub Wiki markdown from the code.
• add a --docs mode to generate the static site documentation.
• add a --sidebar mode to generate a sidebar for the docs and wiki.
• add a --template option to specify a custom template for rendering,
  either
• add a twoslash mode, to inject extra markup into example codeblocks,
  so the types and signatures can be displayed in docs. this is needed so
  that twoslash can detect our package's types and signatures.
• Add .vitepress configuration files.
• Add a custom theme for VitePress (low priority)
• Add a custom twoslash plugin for VitePress.