Improve library API documentation

[MasterKale]

I'm not really happy with the TypeDoc-generated docs that are hosted at https://api-docs.simplewebauthn.dev/. It's primarily because of things like this:

What arguments are within Options? Who knows?!

This is partially my fault for rolling with an old version of TypeDoc that works with a plugin that supports a "library" mode. I chose this approach because early testing produced adequate documentation of the monorepo's multiple libraries, but it just hasn't scaled well as the libraries' have evolved.

Now that I have a proper website up with its own docs section, though, it's feasible for me to start maintaining manually-authored API docs and host them there to achieve the desired level of exposure of the various methods' arguments.

[MasterKale]

I'm looking around for inspiration and found a couple of things that are inspiring me:

React-Table

Their documentation site is Docusaurus-based. API docs is its own section on the sidebar, and each method has its own breakdown of parameters. Here's an example:
https://react-table.tanstack.com/docs/api/useGroupBy

Slack's API

They must use an in-house solution. I really like their "Arguments" section listing out the various options, what's required/optional...:
https://api.slack.com/methods/chat.postMessage

[P4sca1]

I really like the nuxt api docs:
https://nuxtjs.org/api

They have created a template for it along with a git based cms system, which may be interesting for you: https://content.nuxtjs.org/themes/docs

Here are other docs using the docs template by nuxt:
https://pwa.nuxtjs.org/
https://axios.nuxtjs.org/

[MasterKale]

Oh dang, Nuxt has a way for me to quickly get a site like that up and running? I went with Docusaurus because I thought I'd have to wire up my own version of Nuxt's site and opted for something that seemed more turnkey.

I honestly prefer Nuxt's format, though, so I'll take a closer look at the template you linked.

[MasterKale]

TypeDoc has a new beta out that may improve docs output 😮 TypeStrong/typedoc#1364 (comment)

[MasterKale]

Whoops, didn't mean for this to get closed (so that's what happens when you link an issue to a PR 🤔). PR #66 upgraded docs to a beta release of TypeDoc that uses its upcoming Library mode and some of the roughness that inspired this ticket has already gone away.

That said I'm reopening this ticket to continue tracking improvements. I'm still not entirely satisfied, but maybe with some luck I can help the TypeDoc project improve its library mode.

[MasterKale]

I took a look at the shape of the API docs today and I think I'm satisfied enough with them to finally close out this ticket. Thanks to the awesome work delivered by @jstewmon in PR #67 back in December the docs now allow you to drill way down from SimpleWebAuthn-specific types into types defined in TypeScript's DOM library. For example, it's now possible to click through from PublicKeyCredentialRequestOptionsJSON to see types for, say, AuthenticatorTransport:

https://api-docs.simplewebauthn.dev/modules/_simplewebauthn_typescript_types.html#authenticatortransport

I'm satisfied that the API docs are sufficiently useful now.

[cleverplatypus]

Where are the API Docs? https://api-docs.simplewebauthn.dev/ seems to be down.

Cheers

[MasterKale]

The API docs became a huge maintenance burden for me so I took them down a while ago, I can't remember exactly when. It's been my hope that the strong typing throughout the library and the guidance I maintain at https://simplewebauthn.dev/docs/ would be sufficient.