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):
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.
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