[docs] Add API reference to new docs site and cleanup old docs

.gitignore

@@ -7,15 +7,8 @@ __pycache__/
 /skyrl-train/outputs/
 /data/lcb
 
-# Documentation build artifacts
-/skyrl-train/docs/_build/
-docs/_build/
-docs/_static/
-docs/_templates/
-docs/_autosummary/
-docs/api/_autosummary/
-docs/generated/
-docs/_spelling/
+# MkDocs build output (generated during build)
+docs/public/api-ref/
 
 # Documentation cache
 .doctrees/
@@ -62,6 +55,7 @@ downloads/
 eggs/
 .eggs/
 lib/
+!docs/lib/
 lib64/
 parts/
 sdist/

docs/README.md

@@ -1,39 +1,109 @@
 # SkyRL Documentation
 
-This is the documentation site for SkyRL, built with [fumadocs](https://fumadocs.dev/) and Next.js.
+The SkyRL documentation site combines two systems:
 
-## Development
+- **[Fumadocs](https://fumadocs.dev/) + Next.js** for the main user guide (`/docs`)
+- **[MkDocs](https://www.mkdocs.org/) + [mkdocstrings](https://mkdocstrings.github.io/)** for the API reference (`/api-ref`)
+
+Both are served as a single deployment on Vercel.
+
+## Project Structure
+
+```
+docs/
+├── app/                    # Next.js app routes (fumadocs)
+├── content/docs/           # User guide content (.mdx files)
+├── lib/                    # Shared layout config
+├── mkdocs/                 # MkDocs API reference source
+│   ├── mkdocs.yaml         # MkDocs configuration
+│   ├── content/            # API reference markdown files
+│   │   ├── index.md        # API reference landing page
+│   │   ├── data.md         # Data interface API
+│   │   ├── generator.md    # Generator API
+│   │   ├── trainer.md      # Trainer API
+│   │   ├── ...
+│   │   └── stylesheets/    # Custom CSS for MkDocs theme
+│   └── overrides/          # MkDocs Material theme overrides
+├── public/                 # Static assets
+│   └── api-ref/            # (generated) MkDocs build output
+├── middleware.js            # Routes /api-ref/* to MkDocs static files
+├── next.config.mjs          # Next.js configuration
+├── package.json
+└── vercel.json             # Vercel deployment config
+```
+
+## Prerequisites
+
+- **Node.js** >= 18
+- **[uv](https://docs.astral.sh/uv/)** (Python package manager) for building API reference
+- Python packages are installed automatically via `uv sync`
+
+## Local Development
+
+### Fumadocs (User Guide) Only
 
 ```bash
-# Install dependencies
+cd docs
 npm install
-
-# Run dev server
 npm run dev
+```
 
-# Build for production
-npm run build
+This starts the Next.js dev server at `http://localhost:3000`. The API reference at `/api-ref` won't be available unless you build it separately.
 
-# Start production server
+### Build API Reference Locally
+
+```bash
+cd docs
+npm run build:api-ref
+```
+
+This runs `uv sync --extra docs` in `skyrl-train/` and then builds the MkDocs API reference into `docs/public/api-ref/`. You can then access it via the dev server.
+
+### Full Production Build
+
+```bash
+cd docs
+npm install
+npm run build
 npm start
 ```
 
+This builds both the API reference (MkDocs) and the main site (Next.js), then starts the production server.
+
 ## Deployment
 
-This site is deployed on Vercel at [docs.skyrl.ai](https://docs.skyrl.ai).
+Deployed on Vercel at [docs.skyrl.ai](https://docs.skyrl.ai). The Vercel build command (in `vercel.json`) installs `uv`, then runs `npm run build` which chains:
 
-## Adding New Documentation
+1. `uv sync --extra docs` (install Python deps in `skyrl-train/`)
+2. `mkdocs build` (generate API reference HTML into `public/api-ref/`)
+3. `next build` (build the fumadocs site, which includes the static API reference)
 
-1. Create a new `.mdx` file in `content/docs/`
-2. Add frontmatter with title and description:
+## Adding Documentation
+
+### User Guide Pages
+
+1. Create a `.mdx` file in `content/docs/`
+2. Add frontmatter:
    ```mdx
    ---
    title: Your Page Title
    description: A brief description
    ---
 
-   # Your Page Title
-
    Your content here...
    ```
-3. The page will automatically appear in the navigation
+3. Update `content/docs/meta.json` if needed for navigation ordering
+
+### API Reference Pages
+
+1. Create a `.md` file in `mkdocs/content/`
+2. Use mkdocstrings directives to auto-generate from docstrings:
+   ```markdown
+   # Module Name
+
+   ::: skyrl_train.module_name
+       options:
+         show_root_heading: true
+         members_order: source
+   ```
+3. Add the page to the `nav` section in `mkdocs/mkdocs.yaml`

docs/app/docs/layout.tsx

@@ -5,6 +5,15 @@ import { sortPageTree } from '@/lib/sort-tree';
 
 export default function Layout({ children }: LayoutProps<'/docs'>) {
   const tree = sortPageTree(source.getPageTree());
+  tree.children.push({
+    type: 'separator',
+  });
+  tree.children.push({
+    type: 'page',
+    name: 'API Reference',
+    url: '/api-ref/',
+    external: true,
+  });
   return (
     <DocsLayout tree={tree} {...baseOptions()}>
       {children}

docs/middleware.js

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+
+export function middleware(request) {
+  const { pathname } = request.nextUrl;
+
+  // /api-ref or /api-ref/ → serve index.html
+  if (pathname === '/api-ref' || pathname === '/api-ref/') {
+    const url = request.nextUrl.clone();
+    url.pathname = '/api-ref/index.html';
+    return NextResponse.rewrite(url);
+  }
+
+  // /api-ref/foo (no file extension) → serve foo.html
+  if (pathname.startsWith('/api-ref/') && !pathname.match(/\.\w+$/)) {
+    const url = request.nextUrl.clone();
+    url.pathname = pathname.replace(/\/$/, '') + '.html';
+    return NextResponse.rewrite(url);
+  }
+}
+
+export const config = {
+  matcher: ['/api-ref', '/api-ref/:path*'],
+};

docs/mkdocs/content/backends.md

@@ -0,0 +1,9 @@
+# Abstract Backend
+
+The base interface that all Tinker engine backends implement.
+
+::: skyrl.backends.backend.AbstractBackend
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true

docs/mkdocs/content/data.md

@@ -0,0 +1,42 @@
+# Data Interface
+
+Our interface for training data is modelled after [DataProto](https://verl.readthedocs.io/en/latest/api/data.html) in VERL but is much simpler.
+
+## Trainer APIs
+
+::: skyrl_train.training_batch.TensorBatch
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+::: skyrl_train.training_batch.TrainingInput
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+::: skyrl_train.training_batch.TrainingInputBatch
+    options:
+      show_root_heading: true
+      members_order: source
+
+::: skyrl_train.training_batch.TrainingOutputBatch
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+## Generator APIs
+
+::: skyrl_train.generators.GeneratorInput
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+::: skyrl_train.generators.GeneratorOutput
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true

docs/mkdocs/content/entrypoint.md

@@ -0,0 +1,21 @@
+# Entrypoint API
+
+## Training Entrypoint
+
+The main entrypoint is the `BasePPOExp` class which runs the main training loop.
+
+::: skyrl_train.entrypoints.main_base.BasePPOExp
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+## Evaluation Entrypoint
+
+The evaluation-only entrypoint is the `EvalOnlyEntrypoint` class which runs evaluation without training.
+
+::: skyrl_train.entrypoints.main_generate.EvalOnlyEntrypoint
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true

docs/mkdocs/content/env.md

@@ -0,0 +1,31 @@
+# Environment API
+
+The core environment APIs for SkyRL-Gym.
+
+## Core Classes
+
+::: skyrl_gym.core.Env
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+::: skyrl_gym.core.EnvStepOutput
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+## Text Environment
+
+::: skyrl_gym.envs.base_text_env.BaseTextEnv
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+
+::: skyrl_gym.envs.base_text_env.BaseTextEnvStepOutput
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true

docs/mkdocs/content/env_vars.md

@@ -0,0 +1,8 @@
+# Environment Variables
+
+Configuration via environment variables.
+
+::: skyrl_train.env_vars
+    options:
+      show_root_heading: true
+      members_order: source

docs/mkdocs/content/generator.md

@@ -0,0 +1,26 @@
+# Generator API
+
+The Generator is responsible for generating trajectories for training.
+
+## Core APIs
+
+### GeneratorInterface
+
+::: skyrl_train.generators.GeneratorInterface
+    options:
+      show_root_heading: true
+      members_order: source
+
+### InferenceEngineInterface
+
+::: skyrl_train.inference_engines.base.InferenceEngineInterface
+    options:
+      show_root_heading: true
+      members_order: source
+
+### InferenceEngineClient
+
+::: skyrl_train.inference_engines.inference_engine_client.InferenceEngineClient
+    options:
+      show_root_heading: true
+      members_order: source

docs/mkdocs/content/index.md

@@ -0,0 +1,19 @@
+# SkyRL API Reference
+
+## SkyRL
+
+- **Backends** — [Abstract Backend](backends.md), [JAX Backend](jax_backend.md), [SkyRL-Train Backend](skyrl_train_backend.md)
+- [Tinker Engine](tinker.md) — Orchestration engine for RL training
+- [Types](types.md) — Request/response types for the Tinker API
+- [TX Models](tx_models.md) — Model loading and configuration for the JAX backend
+- [Data Interface](data.md) — TensorBatch, TrainingInput, GeneratorInput/Output
+- [Generator](generator.md) — GeneratorInterface, InferenceEngineInterface
+- [Trainer](trainer.md) — RayPPOTrainer, Dispatch, Worker APIs
+- [Entrypoint](entrypoint.md) — BasePPOExp, EvalOnlyEntrypoint
+- [Algorithm Registry](registry.md) — Advantage estimators, policy loss registries
+- [Environment Variables](env_vars.md) — Configuration via environment variables
+
+## SkyRL-Gym
+
+- [Environment](env.md) — Env, BaseTextEnv, step outputs
+- [Tools](tools.md) — ToolGroup, tool decorator

docs/mkdocs/content/jax_backend.md

@@ -0,0 +1,30 @@
+# JAX Backend
+
+JAX-based backend with multi-LoRA adapter support and distributed training.
+
+## Configuration
+
+::: skyrl.backends.jax.JaxBackendConfig
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+      allow_inspection: false
+
+## Backend
+
+::: skyrl.backends.jax.JaxBackend
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+      allow_inspection: false
+
+## Internals
+
+::: skyrl.backends.jax.AccumulatedGradients
+    options:
+      show_root_heading: true
+      members_order: source
+      show_bases: true
+      allow_inspection: false