Add new schema reference pages from custom React component #250
Conversation
|
🚀 Deployed on https://deploy-preview-250--cai-open-source.netlify.app |
…e Definitions toc links
| const AVAILABLE_SCHEMAS = [ | ||
| 'Reader.schema.json', | ||
| 'Builder.schema.json', | ||
| 'ManifestDefinition.schema.json', | ||
| 'Settings.schema.json', | ||
| ]; |
There was a problem hiding this comment.
Hm, I'm not a huge fan of hardcoding this here. Can we render all children of the schemas directory by default but then optionally choose what to display in the sidebars.js code? Not a huge deal, just something that may be more future-proof.
| // Convert [`CodeRef`] to links to docs.rs, preserving code formatting | ||
| html = html.replace(/\[`([^`]+)`\]/g, (m, codeRef) => { | ||
| const url = resolveDocsUrl(codeRef); | ||
| return `<a href="${escapeHtml(url)}"><code>${escapeHtml( | ||
| codeRef, | ||
| )}</code></a>`; | ||
| }); |
There was a problem hiding this comment.
This is great that it links directly do docs.rs! Is it possible to also clear out the extra brackets following the code ref here or some other place in the code?
For example:
Reader::resource_to_stream[crate::Reader::resource_to_stream]
| // Convert [`CodeRef`] to links to docs.rs, preserving code formatting | ||
| html = html.replace(/\[`([^`]+)`\]/g, (m, codeRef) => { | ||
| const url = resolveDocsUrl(codeRef); | ||
| return `<a href="${escapeHtml(url)}"><code>${escapeHtml( | ||
| codeRef, | ||
| )}</code></a>`; | ||
| }); |
There was a problem hiding this comment.
I also noticed that it doesn't take into account the module the struct is in. So for example, AssertionMetadata::region_of_interest references:
https://docs.rs/c2pa/latest/c2pa/struct.AssertionMetadata.html#structfield.region_of_interest
instead of
https://docs.rs/c2pa/latest/c2pa/assertions/struct.AssertionMetadata.html#method.region_of_interest
| // Convert [`CodeRef`] to links to docs.rs, preserving code formatting | ||
| html = html.replace(/\[`([^`]+)`\]/g, (m, codeRef) => { | ||
| const url = resolveDocsUrl(codeRef); | ||
| return `<a href="${escapeHtml(url)}"><code>${escapeHtml( | ||
| codeRef, | ||
| )}</code></a>`; | ||
| }); |
There was a problem hiding this comment.
Last thing about this is that sometimes a code ref doesn't contain the path. For instance, if it's in the same Rust module it may just do [ManifestAssertionKind] and Rust knows where to find ManifestAssertionKind. I'm not sure if it's possible to resolve that. In some cases we can also resolve it to a struct defined in the schema.
Maybe we should also generate JSON schemas for the assertions and they can be referenced from the site?
This PR adds a new custom React component to create reference documentation from the JSON schemas for Reader, Builder, ManifestDefinition, and Settings.
https://deploy-preview-250--cai-open-source.netlify.app/docs/manifest/json-ref/
For now, , the schema JSON files are copied manually into this repo, but should eventually, be copied using a workflow that builds and copies them from c2pa-rs whenever there is a release there.
The intent of this PR is to create reference pages that look similar to what we have now (which are generated using Jekyll code that is not maintainable).
There are still some issues with the links in various places, because the schemas are generated from comments in the Rust code, so they have Rust-style references that are meant for parsing and display in docs.rs.
There are a few other display issues as well.