Feature: SDK Reference generation & hosting #78
Conversation
- Updated the SDK generation workflow to load SDK configurations from `sdks.json`, improving maintainability. - Removed individual SDK generator scripts for CLI, Code Interpreter (JS and Python), and Desktop SDKs, consolidating functionality into a single generator script. - Enhanced the `generate-sdk-reference.sh` script to dynamically handle SDK types and versions. - Cleaned up the workflow YAML file for better readability and consistency in string formatting.
- Updated `.gitignore` to include `sdk_navigation.json` for generated SDK navigation. - Added new styles for version switcher in `style.css`, improving UI for SDK and version selection. - Modified `generate-sdk-nav.js` to group SDKs by family, enhancing navigation structure. - Updated SDK configurations in `sdks.json` to include family and language attributes for better organization. - Improved CLI and Python documentation generation scripts for consistency and added frontmatter to markdown files.
- Updated `sdk-reference-sync.yml` to allow version generation for "all" versions by default. - Modified `generate-sdk-reference.sh` to support a new `--limit` option for controlling the number of versions processed. - Improved `generate-sdk.sh` to filter versions based on a minimum version requirement and to handle version discovery more effectively. - Updated `sdks.json` to include `minVersion` attributes for SDKs, ensuring only compatible versions are processed. - Enhanced common library functions for version management and caching during dependency installation.
- Added verification functions to ensure generated documentation meets quality standards, including checks for empty files and missing frontmatter. - Implemented a logging utility for better output management during the generation process. - Created a `.mintignore` file to exclude specific directories from version control. - Enhanced CLI commands for improved user experience and added options for forced regeneration of existing versions.
- Introduced a new `sdks.config.ts` file to define SDK configurations in TypeScript, enhancing type safety and maintainability. - Removed the outdated `sdks.json` file to streamline the configuration process. - Updated relevant code to utilize the new configuration structure, including adjustments in the CLI and navigation logic. - Improved type definitions for SDK configurations to support additional properties and ensure consistency across the codebase.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
- Updated CSS styles for version switcher to enhance UI consistency and usability. - Modified GitHub Actions workflow to streamline SDK generation input descriptions and improve summary output. - Refactored context handling in SDK generation functions for better clarity and maintainability. - Introduced new utility functions for version validation and normalization, enhancing version management. - Added tests for cache handling and file processing to ensure robustness in SDK reference generation.
- Deleted `package.json` and `pnpm-lock.yaml` files to clean up the project structure as they are no longer needed for SDK reference generation.
- Replaced `basePackage` and `fallbackPackages` with `allowedPackages` in SDK configurations for better clarity and usage. - Refactored the `generateVersion` function to utilize a new `CheckoutManager` for handling repository checkouts and version switching. - Simplified the `generatePydoc` function to focus on allowed packages, removing the need for fallback and submodule handling. - Introduced a new `checkout.ts` file to manage SDK checkouts, enhancing code organization and maintainability. - Removed obsolete cache handling code and related tests to streamline the project structure.
- Enhanced error handling in the CLI to ensure proper exit on validation failures. - Improved logging for workflow abort scenarios in the generator, ensuring clearer output. - Introduced a new function to find the CLI output directory, enhancing the generation process and error reporting for missing markdown files.
…dd versioning documentation
| "pages": [ | ||
| "docs/sdk-reference/js-sdk/1.0.0/errors", | ||
| "docs/sdk-reference/js-sdk/1.0.0/sandbox", | ||
| "docs/sdk-reference/js-sdk/1.0.0/sandbox-filesystem" |
There was a problem hiding this comment.
Inconsistent version path formatting in docs.json entries
Medium Severity
The version field specifies v1.0.0 (with "v" prefix) but the page paths use 1.0.0 (without "v" prefix). This inconsistency appears for multiple SDKs' v1.0.x versions (js-sdk, python-sdk, code-interpreter-python-sdk, cli). The navigation.ts code uses normalizedVersion which includes the "v" prefix when building paths, so these entries don't match expected format. As noted in PR discussion, "versions without v prefix cannot exist." This mismatch could cause broken navigation links or 404 errors.
Additional Locations (2)
| "default": true, | ||
| "pages": [ | ||
| "docs/sdk-reference/js-sdk/v2.9.0/errors", | ||
| "docs/sdk-reference/js-sdk/v2.9.0/sandbox", |
There was a problem hiding this comment.
do you have any mechanism for checking if all the urls are correct for SEO?
There was a problem hiding this comment.
this is an edge case, it should be always in sync but these entries are dev artifacts that i forgot to clean up
There was a problem hiding this comment.
we could add another workflow tho that checks on pr's
| on: | ||
| pull_request: | ||
| paths: | ||
| - "sdk-reference-generator/**" |
There was a problem hiding this comment.
this should be probably changed. I would make it either manually callable, or run on every PR?
| // avoid promoting constructors | ||
| i += 1 | ||
| continue | ||
| } |
There was a problem hiding this comment.
Constructor handler skips extra line unintentionally
Medium Severity
The removeLinesWithConditions function has inconsistent skip logic. For "Extends/Overrides/Inherited from" sections, the comment explicitly states "skip this line and the next three" matching i += 3. However, for ##### new constructor lines, the comment says "avoid promoting constructors" but i += 1 is used. Due to the for loop's i++ increment, this causes 2 lines to be skipped (the constructor line plus the following line) when the intent appears to be skipping only the constructor header. This silently removes documentation content following constructor headers. To skip only the constructor line, the i += 1 should be removed, leaving just continue.
Note
Establishes infrastructure to auto-generate and publish versioned SDK reference docs.
sdk-reference-generator/(TypeScript) with generators (TypeDoc, pydoc, CLI), repo checkout/versioning, file processing, verification, and extensive testsdocs/sdk-reference/anddocs.json, and commits changesdocs.jsonto a versioned SDK Reference navigation (dropdowns for multiple SDKs/versions) replacing the previous single hrefrequirements.txt) and ignore rules (.gitignore,.mintignore)Written by Cursor Bugbot for commit 4eaca6f. This will update automatically on new commits. Configure here.