Many Untitled and undefined identifiers in rendered documentation

[egasimus]

[egasimus]

I assume most of those *.mds are generated from the JSONSchema through an internal script? The missing titles are in the file names but not propagated to the generated document - I couldn't find any code that generates them, though.

I noticed that of the unnamed entities correspond to types from cosmwasm-std. Would you accept a PR for removing those pages and putting an interactive JSONSchema viewer on the main page for each schema? Example 1 Example 2

[ccamel]

Hello @egasimus! Thank you for your interest in the project.

Indeed, we are using an automatic documentation generation tool. This tool is integrated into the okp4/contracts project through the Makefile, which handles the generation of smart contract interfaces and then synchronizes (rsync) the content with the doc project - see tasks.docs-generate. The generation tool we use is adobe/jsonschema2md.

[bdeneux]

Hey @egasimus, thanks for your proposition.

Yes, It is true that the generated documentation is not very readable, I don't know where is the issue, maybe the cosmwasm-schema library that generate the json schema in a invalid format or with missing annotation to add more metadata on attribute or if the issue come from the jsonschema2md tool 🤷‍♂️.

I'm curious to see what could be the result of the json schema viewer on Docusaurus but if the issue come from the schema generation I don't think the schema viewer will work correctly. Let's see that ! 😀

Like @ccamel say, documentation is generated through the makefile on contract repository, I think we need to keep this generation on that side. On docs, I purpose to add a new page to include this json schema viewer plugin, for that, the CI that update the documentation should be updated to also copy json schema file (in the right place for the plugin) inside docusaurus project through rsync. If it's possible, it could be awesome to manage also versioning for this viewer but let's try first if the json schema viewer work correctly. ;)

[bdeneux]

I found this in the schemars documentation. It could resolve the untitled issue maybe : https://graham.cool/schemars/examples/6-doc_comments/#setting-a-custom-title-andor-description-using-doc-comments

[egasimus]

I found this in the schemars documentation. It could resolve the untitled issue maybe : https://graham.cool/schemars/examples/6-doc_comments/#setting-a-custom-title-andor-description-using-doc-comments

Well, it's an option. But IMHO there's no need to clutter the entire Rust codebase with this stuff just to make the broken docs renderer happy. And some of the untitled types like Binary and Uint128 are from dependencies so I'm not sure how to do that on those.

I also found this issue circa 2021. Not gonna lie, I briefly tried working on a PR for that, even found the lonely function that seems to be responsible for titles, but I reconsidered. I'm way more interested in moving the state of CosmWasm tooling forward, than in helping Adobe suck less at JSONSchema 🤷

So... I'm hacking together a CW-friendly contract schema converter/viewer right now 😅 It doesn't attempt to cover the general case, it just focuses on the bits that a CW contract dev/integrator expects (and correspondingly may skip over things that are only relevant in a generic JSONSchema context, but not to the CW contract's API).

I'll send you a PR with the .mds generated by it ASAP, so that we get your API docs out of the current state. Then once the interactive viewer is a little more done, I'll drop you a link to that as well, so you can play around and decide if you want to embed it in your docs.

Btw, I noticed that you're committing the Markdown that's generated from the schema - once into the contracts repo then once more in the docs repo. What is the reason to commit the generated files?