feat(docs): Change license; enhance OpenAPI docs and update homepage#184
feat(docs): Change license; enhance OpenAPI docs and update homepage#184jp-ayyappan wants to merge 17 commits intomainfrom
Conversation
Updates the homepage with new marketing content and styling. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…services Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add decrypt and encrypt collection example code samples. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
OpenAPI Documentation Improvements: - Add dynamic index generation that reads document IDs from generated files - Rename .info.mdx files to index.mdx for cleaner sidebar navigation - Create post-processing script for automated OpenAPI doc updates - Fix sidebar.ts files no longer appearing as navigation items Marketing Homepage Updates: - Update hero subtitle copy for clarity and developer focus - Fix broken links: /quickstart → /getting-started/quickstart - Fix broken links: /category/concepts → /spec/concepts - Fix broken links: /documentation → /introduction - Update Architecture button link - Update Specifications link to /spec - Update Enterprise Solutions link to Virtru data security platform - Remove Deployment Guides button - Remove non-functional icons Footer & Legal: - Add license information to footer (Docs: CC BY 4.0, Code: BSD 3-Clause) - Remove unused iconify-icon from copyright Technical Changes: - Add update-openapi-index npm script with post-generation hook - Import gray-matter for frontmatter parsing - Update vendored OpenAPI policy specs Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Summary of ChangesHello @jp-ayyappan, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the documentation website by improving the OpenAPI documentation system and completely overhauling the marketing homepage. It introduces automated post-processing for API documentation to ensure accurate and clean navigation, alongside a modern, engaging design for the main landing page. Additionally, the project's documentation license has been updated for broader accessibility, and several OpenAPI specifications have been cleaned up by removing outdated certificate management components. New Java code samples were also added to assist developers with TDF collection operations. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The pull request successfully enhances the OpenAPI documentation system by automating index generation and cleaning up the sidebar navigation. The marketing homepage redesign provides a more modern and developer-focused experience. However, there are several technical issues in the new Java code samples, including a typo in an API call and potential resource leaks due to unclosed streams. Additionally, there is substantial code duplication in the OpenAPI preprocessing script and redundant CSS definitions that should be refactored to improve maintainability.
jp-ayyappan
changed the title
These files were auto-generated and should not be included in this PR. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Add SPDX license identifier to help GitHub recognize the Creative Commons license for documentation. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Remove unused styles import from index.tsx - Extract SERVICE_DESCRIPTIONS and CATEGORY_MAPPING constants to reduce code duplication in preprocessing.ts - Both preprocessOpenApiSpecs and updateOpenApiIndex now use shared constants Addresses Gemini Code Assist review comments about maintainability. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Automatically detect APIs not in CATEGORY_MAPPING - Add them to "Other APIs" category - Log warning with list of uncategorized API names - Prevents new APIs from being silently omitted from index Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The preprocessing script now only processes OpenAPI specs. Index generation is deferred to the update-openapi-index script which runs AFTER docs are generated, eliminating spurious warnings about missing .info.mdx files. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
/gemini review |
There was a problem hiding this comment.
Code Review
The pull request successfully updates the documentation license to CC BY 4.0 and introduces a significantly improved marketing homepage with better copy and fixed navigation links. The automation for OpenAPI index generation is a great addition for maintainability. However, there are a few technical issues to address: invalid HTML nesting on the homepage, redundant CSS files that could lead to maintenance confusion, and the use of inline styles in the new homepage sections.
| <p className="hero-subtitle"> | ||
| OpenTDF inverts this model. Policies travel with the data itself, so you can: | ||
| <ul> | ||
| <li>Revoke access after sharing — even after data has left your environment</li> | ||
| <li>Enforce controls in zero-trust environments — no VPN, no network dependency</li> | ||
| <li>Maintain a complete audit trail — know who accessed what, when, and where</li> | ||
| </ul> | ||
| This is data-centric security: protection that's embedded, not bolted on. | ||
| </p> |
There was a problem hiding this comment.
Nesting a <ul> element inside a <p> tag is invalid HTML. Browsers will automatically close the paragraph tag before the list, which can lead to unexpected styling issues and React hydration mismatches.
References
- Ensure HTML elements are correctly nested according to the specification; specifically, block-level elements like
<ul>should not be placed inside inline-level or paragraph elements.
| <section style={{padding: '4rem 0', textAlign: 'center', background: '#f8f9fa'}}> | ||
| <div className="container"> | ||
| <h2 style={{fontSize: '2.5rem', marginBottom: '1rem', color: 'var(--ifm-color-primary)'}}> | ||
| Ready to Protect Your Data? | ||
| </h2> | ||
| <p style={{fontSize: '1.2rem', marginBottom: '2rem', opacity: 0.8}}> | ||
| Choose your path and start building with OpenTDF today. | ||
| </p> | ||
| </Columns.Item> | ||
| </Columns> | ||
| <Features | ||
| title="OpenTDF Examples" | ||
| description="Ideas for leveraging OpenTDF in your own applications" | ||
| imageUrl="" | ||
| > | ||
| {/* <Features.Item title="SecureCycle" description="SecureCycle is a sample application that demonstrates how OpenTDF safeguards private health information ‐ in this case, sensitive data related to period tracking and symptoms." icon="carbon:location-heart" | ||
| callToAction={{ title: 'Learn more', url: 'https://google.com' }} /> */} | ||
| <Features.Item title="Secure IoT Sensor Data" description="From full-motion video to biometric devices, attach access controls and preserve data integrity to guard against data spoofing." icon="carbon:fingerprint-recognition" /> | ||
| <Features.Item title="Secure Data Sharing" description="Securely share data with partners, customers, and suppliers, and maintain control over who can access it." icon="carbon:ai-governance-lifecycle" /> | ||
| </Features> | ||
| <Feedback | ||
| title="Share Your Feedback" | ||
| > | ||
| <p> | ||
| Virtru, the sponsor of the OpenTDF developer community, would love to hear from you! | ||
| </p> | ||
| <p> | ||
| We're developers, too, and as we mature the project, we're curious what you're building, and what kind of problems you may be encountering or are trying to solve. | ||
| </p> | ||
| <p> | ||
| You can provide anonymous feedback (name, email, and company are not required fields on this form), or share your contact information for access to curated resources, updates, and if you request a response. | ||
| </p> | ||
| </Feedback> | ||
| <div style={{display: 'flex', gap: '1rem', justifyContent: 'center', flexWrap: 'wrap'}}> |
There was a problem hiding this comment.
The final CTA section uses inline styles for layout and typography. For better maintainability and consistency with the rest of the page, these styles should be moved to src/css/marketing.css using appropriate classes (e.g., reusing marketing-hero--secondary for the background).
References
- Prefer external or modular CSS over inline styles to ensure consistency, reusability, and easier maintenance.
| @@ -0,0 +1,11 @@ | |||
| /** | |||
| * Post-processing script to update the OpenAPI index page with correct links | |||
There was a problem hiding this comment.
What does this script do? What is the overall change from current behavior to new with this script added?
marythought
left a comment
marythought
left a comment
There was a problem hiding this comment.
My take: this should probably be two separate PRs. One that just updates the license, and a second updating the homepage layout and content that we can get additional review and buy-in for.
4 participants
Summary
This PR changes the license for OpenTDF docs; enhances the OpenAPI documentation system and updates the marketing homepage with improved content and fixed links.
🔗 Preview: https://opentdf-docs-preview-new-home.surge.sh
OpenAPI Documentation Improvements
.info.mdxfiles.info.mdx→index.mdxto prevent duplicate items in sidebarupdate-openapi-indexscript that runs after API doc generationsidebar.tsfiles no longer appear as clickable itemsMarketing Homepage Updates
/quickstart→/getting-started/quickstart/category/concepts→/spec/concepts/documentation→/introductionFooter & Legal
Technical Changes
scripts/update-openapi-index.tsfor post-generation processinggray-matterfor frontmatter parsingTesting
🤖 Generated with Claude Code