Website section with API reference for app

[jasonkuhrt]

What

• Every day docs
• Dry, succinct
• Content ideas:
  • type signatures
  • example snippets
  • relevant recipe links
  • relevant guide links

How

• app
• Generate JSON representation of api docs
  • Prose should come from JSDoc. jsdoc-parse can turn jsdoc into json.
  • Type Signatures should come from TypeScript
  • NOTE TypeDoc supports outputting to JSON and may be enough to achieve the above two points
• build step that transforms JSON content into markdown
  • NOTE If we do use TypeDoc, there is a markdown plugin we can check out
• have website integrate markdown files into site

Related

#210

References

• https://github.com/gcanti/docs-ts
• https://github.com/jsdoc2md/jsdoc-parse
• https://typedoc.org/

[jasonkuhrt]

@Weakky are there any findings from your pass on this issue that you want to share/capture?

We might be able to use or get inspiration from: https://github.com/gcanti/docs-ts.

[Weakky]

Open issue on TypeStrong to support our use-case: TypeStrong/typedoc#639

[Weakky]

Update: JSON output from typedoc doesn't include type information. We therefore cannot use it for transformations

Update: https://github.com/prisma-labs/jsdoc-extractor repo created

[jasonkuhrt]

Scoured links but no gold:

• https://github.com/cevek/ttypescript/
• https://github.com/gcanti/docs-ts/blob/master/src/parser.ts
• https://github.com/eslint/doctrine
• https://github.com/documentationjs/documentation/blob/master/package.json
• https://github.com/TypeStrong/typedoc/tree/master/src/lib
• Expose API for getting JSDoc nodes in TypeScript files microsoft/TypeScript#7393
• https://blog.cloudflare.com/generating-documentation-for-typescript-projects/
• ...

[jasonkuhrt]

Found something quite interesting: https://api-extractor.com/

Via this also found out about https://github.com/microsoft/tsdoc

Trying it out

Observations:

• Does not support namespaced imports, therefore did not work on main package module
• Did work on /testing module

General Notes

• They are based upon TSDoc
• API report concept is nifty, seems like a nice addition to the classical "cover api surface with tests" mantra
• Taking 10 minutes to read the overview section is worth it, clear concise writing there
• See an example here of the website generator output
• See an example here of the markdown generator output
• release tag concept is very cool and overlaps a bit with some of the vision I had for things Nexus could/would do with its API surface (plugins, too).
• looks high quality but also like typedoc a bit OOP oriented
• IIUC the .d.ts rollup feature is not applicable to us because we have multiple entrypoints––but didn't really go into this closely
• Expect we can learn some nice things from the extractor codebase for ours

Conclusion

• Overall not sold, weary of taking on such a large tool
• Believe we can learn a thing or two from its product features (api report, @beta etc.)
• Believe we can learn a thing or two from its implementation (working with TS API)
• Believe we should seriously look at TSDoc

[jasonkuhrt]

We have stuff now.