This crate, located in /docs/sdk, is a collection of rust files that contain documentation.
Context
The main function of this crate is to fill the gap between what can live in e.g. the Papermoon Polkadot documentation website, and the rust code. Its main advantage that it is accessible to polkadot-sdk maintainers, contains examples that are linked to real code, ensuring correctness of all snippets.
Problem
This is mostly done through docify. This crate cannot be used in crates.io, so we cannot have versioning releases of polkadot-sdk-docs in crates.io.
But, it would be awesome if we could. In a PR #6094 we are seeing that it is tricky to document something that is correct in master (e.g. a flag in chain-spec-builder), knowing that the version that is published now in crates.io is older and therefore not compatible yet.
Bring back our manual versioning. We used to have all the rust-docs hosted in paritytech.github.io/polkadot-sdk/master/ to be versioned (note the master in the URL, it can be replaced with each of our stable releases)
Solution 1 is clearly much much better, but if not we should consider 2 as a fallback.
Given that we had the system in the past, I don't think it is that hard to re-implement it in our CI. @alvicsam you might have a better idea about hos feasible this is.
This crate, located in
/docs/sdk, is a collection of rust files that contain documentation.Context
The main function of this crate is to fill the gap between what can live in e.g. the Papermoon Polkadot documentation website, and the rust code. Its main advantage that it is accessible to polkadot-sdk maintainers, contains examples that are linked to real code, ensuring correctness of all snippets.
Problem
This is mostly done through
docify. This crate cannot be used incrates.io, so we cannot have versioning releases ofpolkadot-sdk-docsin crates.io.But, it would be awesome if we could. In a PR #6094 we are seeing that it is tricky to document something that is correct in master (e.g. a flag in
chain-spec-builder), knowing that the version that is published now incrates.iois older and therefore not compatible yet.Solution
masterin the URL, it can be replaced with each of our stable releases)Solution 1 is clearly much much better, but if not we should consider 2 as a fallback.
Given that we had the system in the past, I don't think it is that hard to re-implement it in our CI. @alvicsam you might have a better idea about hos feasible this is.