feat: DSPX-2345 Add SDK Quickstart Guide

[marythought]

This PR adds an SDK Quickstart section with walk-through tutorials for Go and Java SDKs. It also adds an SDK Troubleshooting section.

preview environment with direct link: https://opentdf-docs-preview-dspx-2345.surge.sh/sdks/quickstart

[gemini-code-assist]

Code Review

This pull request introduces comprehensive SDK quickstart guides for Go, Java, and JavaScript/TypeScript, along with a new troubleshooting section. The changes are a great addition to the documentation. My review focuses on ensuring the correctness and consistency of the new documentation and code examples. I've found several instances of incorrect Docusaurus admonition syntax (:::: instead of :::) across the new markdown files. Additionally, there are a few issues in the code snippets, including missing imports in the Go and Java examples and inconsistent endpoint configurations in the JavaScript example. Addressing these points will improve the clarity and usability of the new guides.

[marythought]

/gemini summary

[gemini-code-assist]

Summary of Changes

This pull request significantly enhances the OpenTDF documentation by introducing new, detailed quickstart guides for Go and Java SDKs, alongside a dedicated troubleshooting section for common SDK issues. The changes aim to streamline the developer experience by providing clear, step-by-step instructions for integrating OpenTDF's encryption and attribute-based access control functionalities into applications. Additionally, the core Quickstart guide has been refined to offer more robust installation and platform management advice, ensuring a smoother onboarding process for new users.

Highlights

• New SDK Quickstart Guides: Comprehensive walk-through tutorials have been added for Go and Java SDKs, covering basic encryption/decryption and advanced Attribute-Based Access Control (ABAC) features. A placeholder guide for JavaScript/TypeScript is also included.
• Dedicated SDK Troubleshooting: A new section provides solutions for common SDK-related issues, including authentication failures, TLS certificate errors, connection problems, and insufficient entitlements.
• Enhanced Quickstart Installation Instructions: The main Quickstart guide has been updated with clearer instructions for checking port conflicts, trusting SSL certificates, and managing the local OpenTDF platform, improving the setup experience.
• Improved Documentation Structure and Navigation: The Docusaurus configuration and sidebar generation have been updated to better integrate the new content, and a client-side script was added for hash-based tab synchronization within the documentation.

🧠 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

• README.md
  • Updated the 'Preview Deployment' section with instructions for using unique Surge preview domains, clarifying Surge account requirements, and providing examples.
• code_samples/policy_code/create_attribute.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• code_samples/policy_code/create_namespace.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• code_samples/policy_code/create_subject_condition_set.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• code_samples/policy_code/create_subject_mapping.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• code_samples/policy_code/list_attributes.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• code_samples/policy_code/list_namespaces.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• code_samples/policy_code/list_subject_mapping.mdx
  • Added an 'id' attribute to the
    Details

    tag for improved linking.
• docs/getting-started/managing-platform.mdx
  • Added a tip box referencing the canonical TLS Certificate Guide.
  • Expanded the description of TLS certificate errors to include 'certificate signed by unknown authority' and browser 'Not Secure' warnings.
• docs/getting-started/quickstart.mdx
  • Updated pronouns from 'we'll' to 'you'll' for a more direct tone.
  • Introduced a new 'Step 1: Check for Port Conflicts (Recommended)' section with detailed instructions and examples for identifying and resolving port usage.
  • Renumbered subsequent installation steps to accommodate the new port conflict check.
  • Corrected the curl command URL for check.sh and install.sh scripts from docs.opentdf.io to opentdf.io.
  • Added a note about silent certificate import failures and their symptoms.
  • Simplified otdfctl profile names from platform-otdf-local to platform in examples.
  • Introduced a new 'Step 7: Trust SSL Certificate (If Needed)' section with symptoms and a solution referencing the TLS Certificate Verification guide.
  • Changed the otdfctl policy subject-mappings create action from read to STANDARD_ACTION_DECRYPT in relevant examples.
  • Updated subject_external_selector_value from .clientId to .client_id in subject condition set examples.
  • Added a new 'Troubleshooting' section with common platform installation and setup issues.
  • Added a 'Quick Reference' section summarizing platform management commands, common otdfctl commands, default ports, access points, and test credentials.
• docs/sdks/quickstart/category.json
  • Added a new category definition file to structure the 'SDK Quickstart' section in the documentation sidebar.
• docs/sdks/quickstart/go.mdx
  • Added a new quickstart guide for the Go SDK, covering project setup, SDK installation, basic encryption/decryption, and advanced ABAC features like attribute creation and subject mapping.
  • Included a complete Go code example demonstrating all steps.
• docs/sdks/quickstart/index.mdx
  • Added a new main landing page for the SDK Quickstart, introducing the concept, outlining what users will build, and providing links to language-specific guides (Go, Java, JavaScript/TypeScript).
  • Explained key concepts such as client credentials authentication, TDF format, and connection security considerations.
• docs/sdks/quickstart/java.mdx
  • Added a new quickstart guide for the Java SDK, detailing Maven project setup, SDK installation, basic encryption/decryption, and ABAC features including attribute and subject mapping management.
  • Included a complete Java code example demonstrating all steps.
• docs/sdks/quickstart/javascript.mdx
  • Added a new quickstart guide for the JavaScript/TypeScript SDK, currently marked as 'Coming Soon' with a placeholder message and links to related resources.
• docs/sdks/troubleshooting.mdx
  • Added a new comprehensive troubleshooting guide for common SDK issues, including authentication, certificate errors, connection problems, import errors, permission denied, and resource management.
• docusaurus.config.ts
  • Added src/theme/TabsHashSync.js to clientModules to enable client-side logic for synchronizing Docusaurus tabs with URL hashes.
• sidebars.js
  • Simplified the tutorialSidebar configuration to use Docusaurus's autogenerated feature, streamlining sidebar generation based on file structure.
• src/theme/TabsHashSync.js
  • Added a new client-side JavaScript file to handle Docusaurus tab synchronization based on URL hash, improving navigation to specific sections within tabbed content.

Activity

• The pull request introduces a new SDK Quickstart section with walk-through tutorials for Go and Java SDKs, and an SDK Troubleshooting section.
• Documentation for managing the platform and SDKs has been significantly expanded and refined.
• Minor infrastructure changes were made to support new documentation features and improve installer robustness.
• A review comment highlighted inconsistent endpoints and client ID in the JavaScript SDK example, suggesting alignment with other documentation.
• A review comment pointed out a missing import for the policy package in a Go SDK code snippet.
• A review comment advised against using System.exit(0) for JVM termination in the Java SDK example, suggesting more graceful shutdown mechanisms for production applications.

[eugenioenko]

Hi @marythought , the Quick Start guide is looking really great!

I was able to go through the process successfully, I left a few non-blocking comments along the way for feedback.

Thank you for putting together this updates.

[jp-ayyappan]

🚀