search

bioimage-io / spec-bioimage-io

Specification for the bioimage.io model description file.
https://bioimage-io.github.io/spec-bioimage-io/
MIT License
18 stars 17 forks source link

Adds scripts for generating json schemas for humans #617

Closed Tomaz-Vieira closed 1 month ago

Tomaz-Vieira commented 4 months ago

Adds scripts for generating json schemas for humans, as well as an entry in build.yaml to do it automatically with the other docs. One option (link_to_reused_ref) was causing encoding errors when writing out the HTML. This is marked as deprecated somewhere else in the json-schema-for-humans library code and it might not be in the tested paths. I can investigate that in later PRs if we care enough about it.

This PR also fixes the broken link pointing to the raw json schema.

FynnBe commented 4 months ago

I think the issue with link_to_reused_ref might be that we have recursive types in our spec

Note: If this option is off and the schema contains recursive definitions, the generation will crash!

https://github.com/coveooss/json-schema-for-humans/blob/main/docs/examples/examples_md_default/Configuration.md#7-property-json-schema-for-humans-configuration-file--link_to_reused_ref

So ideally we get rid of the recursive definition (it is probably the yaml dict definition for the config field). There we could just limit the recursion depth.

Because for the docs it is really unintuitive and confusing to have these references across the docs.

Tomaz-Vieira commented 4 months ago

So ideally we get rid of the recursive definition

I don't think we should be adjusting the spec just for the sake of fitting in with a tool for generating documentation. If we can't make this produce what we want, we can just find a different tool that does

FynnBe commented 4 months ago

I was thinking we shouldn't allow infinitely deeply nested custom tool config anyway... This tool we found is great and this is a minor, meaningful change. Let's go ahead and make it work with this tool (and this config)

FynnBe commented 1 month ago

merging this for now. it's orthogonal to everything else and marked WIP... it will be interesting to see if/how we can improve the generated json schemas (and the documentation generated by the script added in this PR) over time...