Generated chain-specific docs for PAPI

Generated chain-specific docs for PAPI

Hi all! I’m pleased to announce an important addition for polkadot-api documentation: generated docs that cover chain apis, based on the metadata.
With these, you can search for apis like limited_teleport_assets, their type parameters, and the docs that metadata provide for them.
Similar to these docs of PJS.
As it is with regular PAPI type generation, these docs represent exact API provided by chain metadata.

Getting the docs

For well-known chains, a hosted version is available at https://chains.papi.how, which is automatically updated.
Such docs can also be generated for any chain, using @polkadot-api/docgen package:

npm install polkadot-api @polkadot-api/docgen
papi add <...>
papi-generate-docs --config <path-to-papi-config> --output <docs_directory>

Under the hood

We’re generating a special version of TypeScript declaration (heavily reusing regular type generation) that later is fed to TypeDoc.
In contrast to generating html / md files directly, this provides better search, more concise look, and allows for type navigation (e.g. go to apis.Core.execute_block, and there click on Types.DigestItem to see DigestItem type definition):
Screen Shot 2024-10-16 at 15.47.30

Improving it further

As it is with all of documentation of this kind, there is a room for improvement.
Aside from minor performance & search issues that we’ll fix shortly, there’s a whole area of deeper issues:
docs come from Rust code, but the navigation native to polkadot-sdk doesn’t work here; some docs are too Rust-specific; some refer to docs that don’t live in the metadata.
But with all the effort devoted to improving Polkadot docs, I’m sure we’ll find a way to improve the situation from the metadata end.
This would not only improve docs for PAPI, but for all client libraries.

Examples

P.S. a huge shout-out to PAPI team for being open to the outside ideas, and for helping along the way: @josep @voliva @carlosala

11 Likes