identity: example of tsdoc rendered in to README

[bnewbold]

Rendered: https://github.com/bluesky-social/atproto/blob/22dd8df32aaf42e8bdba7e13bb04c10ef21fee73/packages/identity/README.md

Proof of concept of adding some tsdoc comments to this library, then using tsdoc-markdown to render it in to the README. I like the simplicity of the approach for these smaller packages, but a couple issues to consider:

• don't love the type signatures here, though in this case that may have a lot to do with the API design itself or use of Zod? eg, feels like all the DidDocument accessors should be on the DidDocument type itself, not separate top-level functions
• i'd prefer the markdown header levels to be one lower so we can wrap all the docs in an H2, maybe we can fudge that
• if we also do typedoc HTML output (eg, via githuib pages), that will include the README, and there will be confusing duplication of docs

[pfrazee]

Not terrible. If the type signatures just did full codeblocks with multiline indentation I think they'd be totally readable

[estrattonbailey]

Wonder if we could patch the generator to use a triple-tick codeblock and then use prettier to clean it up.

[bnewbold]

Updated to render output to an API.md file instead of directly in the README. We could link to this from the top-level README, with the new table format (eg, right under the per-package README links).

Rendered (similar to previously): https://github.com/bluesky-social/atproto/blob/bnewbold/tsdoc-readme/packages/identity/API.md

I can set up these API.md files for the most prominent packages, though i'm a bit ambivalent about the value. I would see them as a placeholder thing until we get a more full-fledged solution in place, like docusaurus or typedoc. The real work would be in the annotations/comments, which would transfer forward.

Separately, I did a pass at trying to the full typedoc HTML generation system to run. It took a couple hours and didn't get it in a good place, I think i'm just not super familiar with TS/JS ecosystem. The workplace setup makes it sort of complex.

[bnewbold]

Discussed with @pfrazee briefly earlier today, and will probably not merge this as-is, with the markdown file output. We'll just wait until we have a full/proper docs website.

Will refactor this PR to keep the tsdoc additions specifically though.