Docs: Replace broken, sprawling jsonschema2md output with 3 compact guides generated by Fadroma

[egasimus]

I wrote a custom JSONSchema renderer over the last few days; it can be found here.

The script is native ES with zero dependencies, so it imposes no new limitations on the doc gen workflow. It can be copied it into the repo, or (once published), it can be consumed from a JS CDN on Node 18+.

The goal was to remove all things that are not relevant to practical usage of the contract API. For example:

As an API consumer, I care about literally none of this JSONSchema metadata which is on every page of the current docs:

And why does each string constant/enum variant need its own page just to be mentioned in the corner at the end of it?

Instead, let's keep the original JSON schemas available to anyone who has a preferred JSON Schema viewer, or wants to use the schemas for validation, etc.

But let's also generate a more concise Markdown overview of each contract and make that the API reference. Here's what those Markdowns look like, as of today.

• JSONSchema->MD by Fadroma Schema Renderer
• MD->HTML by HedgeDoc (will try renering okp4/docs next):

Invaluable benefit of throwing out the frameworks: once again, things start at the beginning.	Compact yet detailed descriptions, incl. enum definitions and cross-linking of non-primitive types:
All messages of a kind are in one place:	More type definitions (previously affected by #273) now render correctly - even the newlines in the tables.
Same as above but some Execute messages:	As a finisher, here's how much code it takes (total, no dependencies other than Node):

Overall, I'm quite happy with how this doc rendering thingy is turning out. I believe this format of API docs makes it way easier to find info on how to interact with the contracts, and is much closer to what a newcomer would need to get started with the OKP4 platform.

Please review this PR and point out if something is missing, wrong, or needs to be clarified further.

P.S. Progress on the interactive schema-browser that I mentioned in #273 can be followed here - and it looks even better than the Hedgedoc screenshots ;-) Since its stack is slightly more complex, for now let's see how the Markdowns go though

[egasimus]

whoops... fixed

[egasimus]

Huh, more build fail.

Guess it's time for me to have another go at running the whole Docusaurus locally.

Btw, kudos for sticking with Yarn 1 👍 Newer versions of that package manager completely jumped the shark. I have reasons to suspect yall would love https://pnpm.io if you gave it a try though

[egasimus]

Surprise surprise - Docusaurus doesn't like the generated Markdown.

Guess it'll take a little more elbow grease. Array<string> tripped up GitHub's built-in Markdown renderer, too

[egasimus]

Okay, so the docusaurus is looking good!

Might be missing a height:100% somewhere...	Not that visible in dark mode tho :) I think there might be enough room on this page to do something with the code ids and code hashes...
Pretty cool, huh?	Might do the old versions next.

I think this is ready for another CI run. Let 'er rip!

[egasimus]

Huh. Any idea what this is? 😅

[ccamel]

@egasimus AFAIU, the job report-new-dependencies relies on organization secrets to be authorized for posting comments in the Pull Request regarding any potential changes made to the package.json file. Nevertheless, since your repository is a fork, GitHub does not transmit these secrets for security reasons, resulting in the failure of the job (with error: Error: Parameter token or opts.auth is required).

No worries. We can go through this error and still proceed with the merge.

[ccamel]

@egasimus My feedback: The result is impressive, and I love the presentation of the documentation, which is not only readable but also highly useful and capable of enhancing the Developer Experience (DX)! 🤩

After the initial review with @amimart, we identified the following areas for improvement:

• Some links are not functioning correctly. For instance, in the documentation of cognitarium (http://localhost:3000/contracts/okp4-cognitarium), the link to StoreLimitsInput (http://localhost:3000/contracts/okp4-cognitarium#StoreLimitsInput) is not working.
• I wonder if we can improve the code formatting. For example, the JSON code here: http://localhost:3000/contracts/okp4-cognitarium#executemsgdeletedata.
• Additionally, I believe there is room for improvement in the source code documentation, specifically in the smart contracts' code, to provide more detailed comments. But this is more on our side.

[egasimus]

No worries. We can go through this error and still proceed with the merge.

Hoped so! :)

I wonder if we can improve the code formatting. For example, the JSON code here: http://localhost:3000/contracts/okp4-cognitarium#executemsgdeletedata.

Yeah, this one stood out to me as well. It's the same in the input schema, missing newlines and all:

Maybe cosmwasm-schema is stripping some newlines - in that case, maybe if you doubled them in the doc string, it would fix itself automatically? Alternatively, it makes sense to move such examples out of the API docs themselves and into a tutorial/guide-type document.

Some links are not functioning correctly. For instance, in the documentation of cognitarium (http://localhost:3000/contracts/okp4-cognitarium), the link to StoreLimitsInput (http://localhost:3000/contracts/okp4-cognitarium#StoreLimitsInput) is not working.

Good catch. This is because Docusausus lowercases the anchor ids. I'll make the script do likewise, and update the PR.

[egasimus]

Okay, this seems to have fixed the inner links.

• Previously, I was only touching files under contracts/. After merging the latest changes from your main branch, this doesn't seem to work anymore, so I've applied the doc generator to all the doc versions in contracts_versioned_docs 🚀 (I still can't see where to switch the docs to an older version, though.)
• You can now regenerate the Markdown docs by running the render.sh script in the corresponding directory after installing Yarn dependencies. 🤖

[egasimus]

Hey guys, any progress on merging this?

[bdeneux]

Hey @egasimus ! Sorry for the delay ! That seems wonderful for the rendering 😍.

On the other hand I prefer to remove all the rendering (render.sh) generation from this docs repository. I suggest you to remove it and let the new generated documentation like you have done. The generation should be done inside the contracts repository (in the makefile), because it could be useful inside this repository to have a well formatted documentation (like is done today with json2schema). Then once the contracts is released, docs repository will fetch and updated the contracts documentation with the new generated ones.

I can take care of the contracts parts if you want.

[egasimus]

On the other hand I prefer to remove all the rendering (render.sh) generation from this docs repository.

Agreed! Since you already have a setup that copies the Markdown files from contracts to docs, then it definitely makes more sense for the JSON->Markdown rendering to happen in contracts.

I can take care of the contracts parts if you want.

Yes, please proceed with what is necessary to finalize this :-)

[egasimus]

I've regenerated the schema docs for old versions and added a footer containing links to the doc generation tool as well as SHA256 checksum of the source schema.

See also: axone-protocol/contracts#342

[egasimus]

Please decide if the footer should be removed and let me know here, so we can finally fix your API docs for good :-)

[antho31]

Let's keep as it is, with the footer :)

[antho31]

Good job!

[amimart]

Awesome, thank you for bringing this, it has great value 🙏

[ccamel]

Great! Thanks so much ❤️

[bdeneux]

Thanks for this 🙏 ! Nice 👍

[egasimus]

My pleasure! 🙇‍♂️