feat(ts-docs): document all 9 public @resq-sw/* packages, not just ui#58
feat(ts-docs): document all 9 public @resq-sw/* packages, not just ui#58WomB0ComB0 merged 1 commit intomainfrom
Conversation
The npm monorepo ships nine non-private packages — analytics, decorators, dsa, helpers, http, logger, rate-limiting, security, ui — but the workflow only generated TypeDoc output for ui. The other eight had public typedefs and JSDoc but no rendered reference. Refactor the template to a multi-package layout matching the .NET / Python / C++ pattern: - env.PUBLIC_PACKAGES lists every public package (sourced manually from packages/*/package.json where private != true). - New "Generate per-package TypeDoc output" step loops over the list, runs typedoc per package, and stages output under OUTPUT_DIR/<pkg>/. A single package failing logs a warning and the loop continues — aborting the whole run on one bad package would leave the other eight stale. - Subsequent post-process steps (rename README → index, prefix bare links, strip breadcrumbs, escape MDX braces) now operate on OUTPUT_DIR collectively rather than packages/ui/generated-docs. - Per-package version banners are injected into each <pkg>/index.md (replacing the single-package .mdx conversion). - A new "Write top-level index" step writes OUTPUT_DIR/README.mdx listing every package with its version (matches the dotnet / python templates). - Tag trigger widened from `@resq-sw/ui@v*` to `@resq-sw/*@v*` so any package release syncs the docs. - Splice already builds hierarchical groups, so each top-level dir under sdks/typescript/api/ becomes its own collapsible package group in the sidebar. Source-repo workflow needs the usual sync-templates.sh follow-up; the next push to that workflow's matching tag (or a manual dispatch) will produce the first multi-package docs PR.
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![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
This pull request updates the TypeScript API documentation workflow to support multiple packages within the monorepo, transitioning from a focus on the @resq-sw/ui package to a comprehensive multi-package structure. The changes include a refactored generation loop, automated version banner injection for each package, and the creation of a top-level index page. Feedback suggests consolidating the Python scripts used for banner injection and index generation into a single step to reduce code duplication and improve maintainability.
| - name: Write top-level index | ||
| # Stitch a small README.mdx at the top of OUTPUT_DIR listing | ||
| # all generated packages with their pinned versions. This is | ||
| # what users land on when clicking "TypeScript" in the | ||
| # Generated Package References sidebar group. | ||
| # | ||
| # Emit .mdx (not .md) because Mintlify's docs.json nav | ||
| # resolver only matches .mdx for explicitly-registered page | ||
| # ids; the splice registers `sdks/typescript/api/README` as | ||
| # the language sub-group's first page. | ||
| env: | ||
| PKG_REF: ${{ env.DOCS_REF_NAME }} | ||
| GH_REPO: ${{ github.repository }} | ||
| run: | | ||
| python3 - <<'PY' > "$OUTPUT_DIR/README.mdx" | ||
| import json | ||
| import os | ||
| import pathlib | ||
|
|
||
| ref_name = os.environ.get("PKG_REF", "main") | ||
| repo = os.environ.get("GH_REPO", "") | ||
| out = pathlib.Path(os.environ["OUTPUT_DIR"]) | ||
|
|
||
| def read_version(pkg: str) -> str: | ||
| pkg_json = pathlib.Path("packages") / pkg / "package.json" | ||
| if not pkg_json.exists(): | ||
| return "unknown" | ||
| try: | ||
| return json.loads( | ||
| pkg_json.read_text(encoding="utf-8") | ||
| ).get("version", "unknown") | ||
| except json.JSONDecodeError: | ||
| return "unknown" | ||
|
|
||
| print("# ResQ TypeScript SDK") | ||
| print() | ||
| print( | ||
| f"Auto-generated reference for " | ||
| f"[`{repo}`](https://github.com/{repo}) " | ||
| f"at ref `{ref_name}`." | ||
| ) | ||
| print() | ||
| print("## Packages") | ||
| print() | ||
| for pkg_dir in sorted(out.iterdir()): | ||
| if not pkg_dir.is_dir(): | ||
| continue | ||
| version = read_version(pkg_dir.name) | ||
| print(f"- `@resq-sw/{pkg_dir.name}` — `v{version}`") | ||
| PY |
There was a problem hiding this comment.
This step and the 'Inject per-package version banners' step both iterate over the package directories and read package.json files to get version numbers. This introduces code duplication. To improve maintainability, you could merge these two steps into a single Python script. The script could inject the version banners into each package's index.md and also collect the information needed to generate the top-level README.mdx in a single loop.
After the multi-package TS refactor (#58), each package showed up twice in the TypeScript sub-group: - once as a standalone PAGE entry (e.g. \`analytics\`) - once as a collapsible GROUP entry (\`{group: \"analytics\", pages: [\"analytics/index/...\"]}\`) Root cause: the splice's \`/index\` strip turned \`analytics/index\` into the bare path \`analytics\`, which got registered as a leaf file at the parent level. Then \`analytics/index/classes/Analytics\` (and siblings) created a sibling \`analytics/\` directory tree. Both ended up in the parent group's pages list. Fix: introduce \`insert_landing()\` which stores the landing page id on the dir node itself (\`_landing\`) rather than as a sibling \`_files\` leaf. \`to_mintlify\` emits \`_landing\` first inside the dir's group, before any \`_files\` or sub-\`_dirs\`. Result: each package gets exactly one collapsible group, with its landing page as the first child. Applied to both: - automation/source-repo-templates/api-docs.typescript.yml (used at doc-generation time) - scripts/splice-sdk-nav.py (used for local re-splicing across all languages: TS, .NET, Python, Rust, C++) docs.json re-spliced locally to clear the duplicates already on main from PR #60. Co-authored-by: Mike Odnis <engineer@resq.software>
2 participants
Summary
The npm monorepo ships nine non-private packages — `analytics`, `decorators`, `dsa`, `helpers`, `http`, `logger`, `rate-limiting`, `security`, `ui` — but the workflow only generated TypeDoc output for `ui`. The other eight had public typedefs and JSDoc but no rendered reference in the docs site.
Refactor
Bring the TS template up to the multi-package pattern already used by .NET, Python, and C++:
A single package failing typedoc logs a warning and the loop continues — aborting the whole run on one bad package would leave the other eight stale.
Files changed
Test plan