Docs: vitepress

[jankapunkt]

Summary

This finally moves our docs from readthedocs.io and rst files to vitepress and markdown.
Why? Vitepress is super easy to setup and learn. Markdown is super easy.
Readthedocs and rst are super powerful but also a huge entry barrier for others to support us with helping our for documentation.

Additionally, we generate the api docs now directly from JSDoc into markdown that we then serve using vitepress.
Finally, we can now host the docs on GitHub and build them via CI

Linked issue(s)

#118

Involved parts of the project

docs

Added tests?

none

OAuth2 standard

none

Reproduction

clone/checkout the branch docs/vitepress then run

npm run docs:setup #once
npm run docs:api # build api docs from jsdoc
npm run docs:dev # dev mode of vitepress

Preparation for TypeScript transformation

The extended JSDoc can also act as a foundation for a future full TypeScript transformation.
Currently, I added a Model class, that acts solely as Documentation helper but is also usable
as Model wrapper (which I added to the tests to see nothing breaks by its introduction).

Not using the Model class makes no differences from a runtime view of things,
however, using it brings better intellisense and type support.

Please note

The docs are still not 100% complete, especially useful beginner examples or workflow overviews (with the respective methods, not just the abstract workflow from the RFC) are still missing. For that, we could use a nice plugins, such as (https://emersonbottero.github.io/vitepress-plugin-mermaid/)

However, I think we should tackle them in a future PR and use this one as a foundation to make it easier to contribute to docs.

[Copilot]

Pull request overview

This PR migrates the documentation from readthedocs.io (Sphinx/RST) to VitePress (Markdown), making documentation easier to maintain and contribute to. The changes include:

• Migration from RST to Markdown documentation format
• Addition of JSDoc comments to generate API documentation from source code
• Introduction of a Model.from() factory method to create model instances
• Updated all tests to use the new Model.from() wrapper
• New npm scripts for building and serving documentation

Reviewed changes

Copilot reviewed 141 out of 152 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/**/*_test.js	Updated all test files to use Model.from() factory method for model creation
lib/model.js	New Model class with factory method and comprehensive JSDoc documentation
lib/**/*.js	Added JSDoc comments and changed comment style from /** to /* for module dependencies
package.json	Added jsdoc-to-markdown and vitepress dependencies, new documentation scripts
lib/utils/*.js	Refactored to use named exports and added JSDoc comments
lib/pkce/pkce.js	Refactored to use named function exports with JSDoc
docs/**/*.rst	Removed old Sphinx/RST documentation files
docs/**/*.md	Added new Markdown documentation files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dhensby]

Are we meant to have all these docs/.vitepress/cache/* files committed? I'd usually expect these files to be ignored but stored in the CI cache instead.

[jankapunkt]

Indeed, the Vitepress cache and dist folders should be in the gitignore