Skip to content

docs(tutorials): rewrite index as table with Colab badge column#640

Merged
burtenshaw merged 7 commits into
huggingface:mainfrom
sergiopaniego:feature/tutorials-index
May 5, 2026
Merged

docs(tutorials): rewrite index as table with Colab badge column#640
burtenshaw merged 7 commits into
huggingface:mainfrom
sergiopaniego:feature/tutorials-index

Conversation

@sergiopaniego

Copy link
Copy Markdown
Member

Summary

Rewrites docs/source/tutorials/index.md from a minimal bullet list into a table that describes what each tutorial covers and whether a GPU is required. The toctree isupdated to include all eight tutorials in the current + in-progress set.

Must be merged after all prerequisite PRs below. Until those land, the Sphinx build will warn about missing pages (end-to-end-walkthrough, sft-warmup, rubrics, mcp-environment, evaluation-inspect).

Prerequisites (merge in any order before this PR)

PR Tutorial added
#601 wordle-grpo migrated to environment_factory
#599 rubrics — composable reward computation
#602 mcp-environment — MCP tools in training and eval
#618 end-to-end-walkthrough — full GRPO pipeline
#628 evaluation-inspect — evaluating with Inspect AI
#471 feature/harness-interface — required by #636
#636 sft-warmup — SFT warm-up for GRPO

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • New environment
  • Refactoring

Alignment Checklist

Before submitting, verify:

  • I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
  • I have checked .claude/docs/INVARIANTS.md and no invariants are violated
  • I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

RFC Status

  • Not required (bug fix, docs, minor refactoring)

Test Plan

  • After all prerequisite PRs are merged, rebase this branch on main
  • Run cd docs && make html — build should complete with zero warnings about missing tutorial pages
  • Open _build/html/tutorials/index.html — confirm table renders correctly with all 8 rows linked

Claude Code Review

Automated Checks

  • Lint: PASS (docs-only change)
  • Debug code: CLEAN

Tier 1: Fixes Required

None.

Tier 2: Alignment Discussion

None. Pure docs rewrite with no API surface changes.

sergiopaniego and others added 4 commits May 5, 2026 09:38
Replaces the minimal bullet list with a table describing what each tutorial
covers and whether a GPU is required. Includes all eight tutorials from the
current and in-progress PR set.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label May 5, 2026
@greptile-apps

greptile-apps Bot commented May 5, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR rewrites docs/source/tutorials/index.md from a short bullet list into a structured table that describes each tutorial's scope, GPU requirement, and provides Colab launch badges. The toctree is also expanded from 3 to 8 entries to cover the full tutorial set being added by prerequisite PRs.

  • The table format is a clear improvement: GPU requirements and Colab links are now scannable at a glance.
  • One Colab badge link (Wordle GRPO row) is broken — it links to a plain github.com/huggingface/trl/blob/... URL rather than the colab.research.google.com/github/... equivalent; users clicking that badge will land in GitHub's file viewer instead of Colab.
  • Five toctree entries (end-to-end-walkthrough, sft-warmup, rubrics, mcp-environment, evaluation-inspect) reference pages not yet merged, which will produce Sphinx warnings until the listed prerequisite PRs land.

Confidence Score: 4/5

Safe to merge after fixing the broken Colab link; the rest of the change is straightforward documentation.

The Wordle GRPO 'Open In Colab' badge navigates to a raw GitHub blob URL instead of Colab, so every user who clicks it on the published docs will land in GitHub's file viewer instead of opening the notebook. The fix is a one-word prefix change to the URL. Everything else in the PR — table layout, GPU flags, descriptions, toctree ordering — looks correct.

docs/source/tutorials/index.md — specifically line 6, the Wordle GRPO Colab badge URL.

Important Files Changed

Filename Overview
docs/source/tutorials/index.md Rewrites tutorial listing from bullet list to a rich table with GPU indicator and Colab badge columns; toctree expanded to 8 entries. One Colab badge link is broken (points to a GitHub blob URL instead of a Colab URL).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Tutorials Index Page] --> B[Table Row: OpenEnv Tutorial]
    A --> C[Table Row: Wordle GRPO]
    A --> D[Table Row: RL Training 2048]
    A --> E[Table Row: End-to-end Walkthrough]
    A --> F[Table Row: SFT Warm-up for GRPO]
    A --> G[Table Row: Rubrics]
    A --> H[Table Row: MCP Tools]
    A --> I[Table Row: Evaluating with Inspect AI]
    B --> B1["Colab: colab.research.google.com - OK"]
    C --> C1["Colab: github.com/huggingface/trl - WRONG HOST"]
    D --> D1["No notebook"]
    E --> E1["Colab: colab.research.google.com - OK"]
    F --> F1["Colab: colab.research.google.com - OK"]
    G --> G1["Colab: colab.research.google.com - OK"]
    H --> H1["Colab: colab.research.google.com - OK"]
    I --> I1["Colab: colab.research.google.com - OK"]
Loading
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/source/tutorials/index.md:6
The "Open In Colab" badge for the Wordle GRPO row links to a plain GitHub blob URL (`github.com/huggingface/trl/blob/...`) instead of the `colab.research.google.com/github/...` form. Clicking the badge takes users to GitHub's file viewer rather than opening the notebook in Colab, which defeats the purpose of the badge entirely.

```suggestion
| [Wordle GRPO](wordle-grpo.md) | Train an agent to play Wordle using GRPO via TRL's `environment_factory`. Shows the multi-turn tool-calling loop: the model guesses a word each turn and receives letter-position feedback until it wins or the episode ends. | Yes | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/huggingface/trl/blob/main/examples/notebooks/openenv_wordle_grpo.ipynb) |
```

Reviews (1): Last reviewed commit: "docs(tutorials): add Colab badge for MCP..." | Re-trigger Greptile

Comment thread docs/source/tutorials/index.md Outdated

@burtenshaw burtenshaw left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved per maintainer merge request after required checks passed.

@burtenshaw burtenshaw left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved per maintainer merge request after conflict resolution and required checks passed.

@burtenshaw burtenshaw merged commit d625039 into huggingface:main May 5, 2026
9 checks passed
@sergiopaniego sergiopaniego deleted the feature/tutorials-index branch May 6, 2026 07:49
@sergiopaniego sergiopaniego restored the feature/tutorials-index branch May 6, 2026 07:50
@sergiopaniego sergiopaniego deleted the feature/tutorials-index branch May 6, 2026 07:51
@burtenshaw burtenshaw mentioned this pull request May 6, 2026
17 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants