Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds scripts for generating json schemas for humans #617

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

Tomaz-Vieira
Copy link
Contributor

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.

@github-actions github-actions bot added ci Continuous Integration documentation Improvements or additions to documentation enhancement New feature or request github_actions Pull requests that update Github_actions code labels Jul 11, 2024
@FynnBe
Copy link
Member

FynnBe commented Jul 12, 2024

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
Copy link
Contributor Author

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
Copy link
Member

FynnBe commented Jul 23, 2024

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)

This was referenced Oct 10, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ci Continuous Integration documentation Improvements or additions to documentation enhancement New feature or request github_actions Pull requests that update Github_actions code
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants