[docs] Add API reference to new docs site and cleanup old docs#1177
[docs] Add API reference to new docs site and cleanup old docs#1177
Conversation
Signed-off-by: SumanthRH <sumanthrh99@gmail.com>
Signed-off-by: SumanthRH <sumanthrh99@gmail.com>
- Switch to Inter font, white primary palette, blue accent - Override header: white background with thin border-bottom - Override tabs: subtle, no colored background - Lighter sidebar with more spacing - Minimal footer (copyright only, no prev/next nav) - Fumadocs-style tables, subtler admonitions, rounded code blocks - Full dark mode support throughout Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add mkdocs.embed.yaml for API-only MkDocs build (docs_dir: new_docs/api) - Add Next.js middleware for /api-ref trailing slash + index.html resolution - Update next.config.mjs with skipTrailingSlashRedirect - Update package.json build script to chain mkdocs build → next build - Update vercel.json to install uv during Vercel build - Add API Reference nav link in fumadocs layout - Add API reference landing page (api/index.md) - Gitignore build artifacts (docs/public/api-ref/) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Delete skyrl-train/docs/ (old Sphinx RST, fully migrated) - Delete skyrl-train/new_docs/ user guide content (duplicates fumadocs) - Delete skyrl-train/mkdocs.yaml (standalone config, no longer needed) - Move MkDocs API ref source files to docs/mkdocs/ - Fix /api-ref routing with <base> tag instead of redirect (avoids loops) - Add "Back to Docs" link in API reference sidebar - Update build scripts, README, .readthedocs.yaml, .gitignore Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
# Conflicts: # docs/lib/layout.shared.tsx # skyrl-train/docs/algorithms/custom_algorithms.rst # skyrl-train/docs/configuration/config.rst # skyrl-train/docs/examples/flash_rl.rst # skyrl-train/uv.lock
Add API reference pages for the root skyrl/ package (backends, tinker engine, types, TX models) and restructure nav under a "SkyRL" section. Fix the <base> tag to be page-specific so TOC anchor links resolve against the current page instead of always going to the index. Remove non-existent extra_css reference and disable navigation.instant to prevent anchor link breakage. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
SumanthRH
changed the title
Append API Reference as the last item in the fumadocs sidebar page tree instead of the top navbar. Simplify the API reference index page by removing the description sentence and flattening SkyRL-Train entries. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![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 significantly refactors the documentation system by migrating from Sphinx to a hybrid approach using Fumadocs for the user guide and MkDocs for the API reference. Key changes include updating the .gitignore to reflect new build artifacts and explicitly include docs/lib, a complete rewrite of the docs/README.md to detail the new dual-system setup, development workflows, and deployment instructions, and the addition of a Next.js middleware (docs/middleware.js) to correctly route requests to the static MkDocs API reference pages under /api-ref/. Numerous new Markdown files (docs/mkdocs/content/*.md) were introduced to define the API reference structure, utilizing mkdocstrings directives to auto-generate content from Python code. The docs/mkdocs/mkdocs.yaml configures the MkDocs build process, theme, plugins, and navigation, while custom CSS (docs/mkdocs/content/stylesheets/custom.css) and HTML overrides (docs/mkdocs/overrides/main.html, docs/mkdocs/overrides/partials/footer.html) ensure visual consistency with Fumadocs. Build scripts in docs/package.json and docs/vercel.json were updated to orchestrate the uv, mkdocs, and next build commands, and pyproject.toml was modified to include necessary mkdocstrings and pymdown-extensions dependencies. Additionally, all old Sphinx-related documentation files and build scripts were removed. A review comment suggested simplifying the docs/middleware.js logic for better readability by combining conditional blocks for path rewriting.
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
…etion Upstream PR #1177 migrated docs to docs/mkdocs/ and deleted skyrl-train/docs/. Accept the deletion and drop local SkyRLConfig→SkyRLTrainConfig renames in the old RST files (new docs don't reference these). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2 participants
What does this PR do?
This PR integrates a MkDocs-based API reference into the Fumadocs (Next.js) documentation site, served at /api-ref/, and cleans up legacy documentation artifacts.
Changes
API Reference Site (MkDocs + mkdocstrings)
Routing & Embedding
Build & Dependencies
mkdocstrings[python]andpymdown-extensionsto root pyproject.toml dev dependenciesskyrl/tinker/__init__.pyso griffe can discover the tinker packageallow_inspection: falseto avoid conflicting dependency issues. Better documentation for the jax backend will be added in a follow-up PRScreen.Recording.2026-02-18.at.4.16.14.PM.2.mov