Autogenerate JS Core API Docs

[lidel]

Problem

Right now JS Core API docs are maintained by hand as a directory with bunch of Markdown files.

This is unsustainable, docs often get out of date (https://github.com/ipfs/js-ipfs/pull/4013, https://github.com/ipfs/js-ipfs/pull/3990, https://github.com/ipfs/js-ipfs/pull/4014, #3911, etc), wasting everyone's time.

Proposed solution

• Create automation that ensures that JS API docs reflect the API in the latest release
  • We have TypeScript type definitions and could extend existing descriptions in JSDoc
• It could live at https://docs.ipfs.io/reference/js/api/,
  • prior art: auto-generated docs for RPC over HTTP at https://docs.ipfs.io/reference/http/api/ are generated by this CI workflow

cc @achingbrain @BigLep + @hugomrdias if there is any prior art for doing this in JS land

[hugomrdias]

The end goal was always to use https://typedoc.org/ to gen the docs, we didnt do it because the output wasn't always the best because of legacy cjs code. You can check nft.storage client workflow https://github.com/nftstorage/nft.storage/blob/main/.github/workflows/client.yml#L79 and output https://nftstorage.github.io/nft.storage/client

[galargh]

I think this might be a pretty interesting task for one of our Dev Productivity Launchpad Cadets. According to the schedule, they'll start working on issues after Feb 21. Would that timeline work here?

[laurentsenta]

👋 I took a quick shot at this issue to try to move it forward, without much success yet,

It's not straightforward to point typedoc to ipfs-core/index.ts and get a "good looking" documentation, it looks like typedoc doesn't resolve references import, so all we get are empty API types. (also some of our interfaces seemed to break typedoc's parser)

There is a monorepo configuration with typedoc, but I couldn't get it to work. It looks like our setup confuses typedoc: it tries to load our index.js and find its source typescript. Which doesn't exist.

I did manage to generate an equivalent of the current doc by pointing typedoc at the ipfs-core-types folder and marking every ts file as an entry point.

• In Markdown
• In HTML form
• For comparison:
  • generated bitswap
  • original

I see a few options:

• Invest into typedoc to make it work with our codebase and use it /everywhere/,
• Build our own solution, just the minimum that works with this codebase,
• Look into other tools such as jsdoc with better-docs plugin.

Notes with all the commands & experiments I ran:

https://gist.github.com/laurentsenta/aa7c70a0b83880abe9b6ad0ffd34d488

[SgtPooki]

@laurentsenta @galargh

Laurent, are you planning on taking this on?

[laurentsenta]

@SgtPooki Not right now, feel free to take over,

[SgtPooki]

js-ipfs is being deprecated in favor of Helia. You can https://github.com/ipfs/js-ipfs/issues/4336 and read the migration guide.

Please feel to reopen with any comments by 2023-06-02. We will do a final pass on reopened issues afterward (see https://github.com/ipfs/js-ipfs/issues/4336).