Generating chain-specific documentation

polkadot-api / polkadot-api-docs

Docs for polkadot-api

https://papi.how

2 stars 7 forks source link

Generating chain-specific documentation #29

Closed mutantcornholio closed 1 month ago

mutantcornholio commented 2 months ago

Script generates docs for all listed known chains except rococo (it's being shut down).

In dev, they are served separately, to ensure quick feedback in vocs dev. In prod, they are rendered right into vocs output dir, for simplicity.

Had to hack around vocs a bit, hopefully this won't be required for long.

Question how to update the docs automatically is still not addressed, we might think on it a bit more.
There's no good way to trigger GHA on metadata changes, but we could just regenerate docs once a week.

And, if we're to consider automatic docs regeneration, should we also consider bumping papi version to the latest?

Here's the beta: https://papi-how.ghp.mcornholio.ru/getting-started

mutantcornholio commented 2 months ago

cc/ @josepot @voliva @carlosala

mutantcornholio commented 2 months ago

up :)

hitchhooker commented 1 month ago

pump it louder! its over dozen times i've entered papi docs for looking for onchain calls and this PR seems to be answer.

carlosala commented 1 month ago

Hi Yuri! Thank you so much for your PR! After a long internal discussion, we decided to keep both the chain documentation and the internal papi documentation in separate docs, with separate build processes. We'll re-generate daily the chain documentation to ensure that it will always match what users find in the runtime. Hacking around vocs is a bit messy, that's why we decided to keep it separated. Again, I'm deeply grateful for the work, and https://chains.papi.how is live, and linked inside https://papi.how.

Carlo

mutantcornholio commented 1 month ago

@carlosala thanks for releasing the docs!

Couple of issues that I think we need to address though:

https://chains.papi.how/ is deployed as a single module for all the chains, which has two downsides:
- Performance. They are slow. Compare the navigation times with https://papi-how.ghp.mcornholio.ru/chains/polkadot/, for example
- Search is affected. Type anything in search and you'll get duplicates for each of the networks. Which is probably not how the users want to work with it. I expect users to go to specific network first, and search only there. I suggest rolling back the change https://github.com/polkadot-api/polkadot-api/pull/780
The docs generation is not mentioned anyhow in https://papi.how, so it's not really clear that it's possible to generate the docs for any network at all. Maybe move this "about" page back?

mutantcornholio commented 1 month ago

@carlosala what was the reason for merging the docs into a single bundle anyway? Lack of the index page with chains list?

carlosala commented 1 month ago

@carlosala what was the reason for merging the docs into a single bundle anyway? Lack of the index page with chains list?

Basically yes, there was no index at all.

mutantcornholio commented 1 month ago

The way I see it, the downsides overweigh. What if I just create an html template for the index, and reverse the change? UPD: actually, the index page would also be a nice place for the "about" page as well!

carlosala commented 1 month ago

Yeah, sounds good! Feel free to open a PR! 👍🏻 Thanks!

mutantcornholio commented 1 month ago

Here it is: https://github.com/polkadot-api/polkadot-api/pull/800

In the meantime, closing this PR, as it's not needed anymore