Documentation NeMo Gym — Maintenance

Compétence unifiée pour ajouter, mettre à jour, déplacer et supprimer des pages sur le site de documentation NeMo Gym Fern.

Règle de Portée

TOUS les édits de documentation se font sous fern/. Le répertoire hérité docs/ est la source Sphinx originale — n'y ajoutez pas de nouvelles pages. Les notes de version, guides de migration et chaque nouvelle page appartiennent à fern/.

Miroir deux versions. Gym maintient deux arbres de versions réels en parallèle : fern/versions/latest/ et fern/versions/v0.2/. Sauf si l'utilisateur en décide autrement, chaque modification apportée à latest doit être mirrorée vers v0.2 (et vice versa pour les rétroportages). Le PM tient particulièrement à la fidélité entre les versions ; ne les laissez pas diverger.

Disposition en Coup d'Œil

fern/
├── fern.config.json          # Org + version CLI Fern (actuellement 4.80.3)
├── package.json              # `npm run dev|check|generate` — enveloppe `npx -y fern-api@latest`
├── docs.yml                  # Config du site : instances, versions, onglets, redirections, librairies
├── versions/
│   ├── _nav_order.yml        # Ordonnancement nav entre versions
│   ├── latest.yml            # Arbre de nav pour la branche actuelle
│   ├── latest/pages/         # Contenu MDX pour la branche actuelle
│   ├── v0.2.yml              # Arbre de nav pour la branche 0.2
│   └── v0.2/pages/           # Contenu MDX pour la branche 0.2
├── components/               # TSX personnalisé (CTAButtons, NavButton, CustomFooter)
├── assets/                   # Images, SVG, favicon
├── main.css                  # Surcouches de thème global (vert NVIDIA, espacements des badges, etc.)
└── product-docs/             # Référence de librairie GÉNÉRÉE (gitignorée)

Système de fichiers                                         URL Publiée
──────────────────────────────────────────────────────────  ──────────────────────────────────
fern/versions/latest/pages/get-started/quickstart.mdx       docs.nvidia.com/nemo/gym/latest/get-started/quickstart
fern/versions/v0.2/pages/get-started/quickstart.mdx         docs.nvidia.com/nemo/gym/v0.2/get-started/quickstart

Opérations

Ajouter une Page

1. Rassemblez : titre de la page, section cible, nom de fichier (kebab-case .mdx), sous-répertoire sous fern/versions/latest/pages/.

2. Créez fern/versions/latest/pages/<subdirectory>/<filename>.mdx :

   ---
   title: "<Page Title>"
   description: "Description SEO d'une ligne (ou chaîne vide)"
   position: 3
   ---
   
   # <Page Title>
   
   <content>

3. Si le dossier parent est monté dans latest.yml avec title-source: frontmatter, la page est auto-découverte — aucune modification de nav requise. Sinon, ajoutez une entrée - page: sous la bonne section: dans fern/versions/latest.yml.

4. Miroir vers v0.2 : copiez le MDX vers fern/versions/v0.2/pages/<subdirectory>/<filename>.mdx et mettez à jour tous les liens /latest/... de son corps vers /v0.2/.... Mettez à jour v0.2.yml si une entrée nav manuelle était nécessaire.

Mettre à Jour une Page

1. Localisez par chemin, titre ou mot-clé (grep -rn dans fern/versions/latest/pages/).
2. Contenu seulement — éditez le MDX directement, puis mirrorisez la même modification vers la copie v0.2.
3. Changement de titre — mettez à jour le frontmatter title: et (si le parent utilise title-source: frontmatter) rien d'autre ; sinon, mettez aussi à jour l'entrée nav - page:.
4. Déplacement de section — git mv le fichier, mettez à jour son path: dans la nav, corrigez tous les liens entrants, mirrorisez vers v0.2.
5. Changement de slug — les dossiers utilisent le nom de fichier de la page pour le slug. Renommer le fichier change l'URL ; ajoutez une redirection dans fern/docs.yml pour que l'ancienne URL continue de fonctionner.

Supprimer une Page

1. Trouvez les liens entrants : grep -rn "<filename>" fern/versions/latest/pages fern/versions/v0.2/pages --include="*.mdx".
2. git rm le fichier de latest/ et v0.2/.
3. Supprimez le bloc - page: correspondant de latest.yml et v0.2.yml s'il s'agissait d'une entrée manuelle.
4. Corrigez ou supprimez tous les liens entrants.
5. Ajoutez une redirection dans fern/docs.yml si l'URL était publique.

Rétroportage vers une Version Antérieure

Quand latest et v0.2 divergent intentionnellement (par ex. une API n'existe que dans latest), ne mirrorisez pas — mais signalez la divergence dans la description de la PR pour que le PM puisse confirmer.

Exemple Travaillé : Ajouter une Page

Demande : « Ajouter un how-to pour la collecte de rollouts sous Get Started. »

1. Créez fern/versions/latest/pages/get-started/rollout-collection.mdx :

   ---
   title: "Collect Rollouts"
   description: "Run the agent against your dataset and write results to JSONL"
   position: 4
   ---
   
   # Collect Rollouts
   
   <content>

2. Le dossier get-started dans latest.yml utilise title-source: frontmatter, donc la page apparaît automatiquement. position: 4 contrôle l'ordre.

3. Mirrorisez vers fern/versions/v0.2/pages/get-started/rollout-collection.mdx. Remplacez tous les liens /latest/... du corps par /v0.2/....

4. cd fern && npm run check && npm run dev, vérifiez que /latest/get-started/rollout-collection et /v0.2/get-started/rollout-collection s'affichent.

Exemple Travaillé : Renommer un Slug (avec Redirection)

Demande : « Renommer /latest/get-started/setup en /latest/get-started/detailed-setup. »

1. git mv fern/versions/latest/pages/get-started/setup.mdx fern/versions/latest/pages/get-started/detailed-setup.mdx.

2. Mirrorisez le renommage vers v0.2.

3. Ajoutez les redirections dans fern/docs.yml :

   redirects:
     - source: "/latest/get-started/setup"
       destination: "/latest/get-started/detailed-setup"
     - source: "/v0.2/get-started/setup"
       destination: "/v0.2/get-started/detailed-setup"

4. grep -rn "/get-started/setup" fern/versions/ et mettez à jour tous les liens entrants dans les deux versions.

Directives de Contenu

NeMo Gym utilise les composants MDX natifs de Fern directement. N'utilisez pas la syntaxe GitHub > [!NOTE] — elle ne s'affichera pas.

Les images vivent dans fern/assets/ (partagées) ou sous pages/ d'une version (version-scoped). Référencez avec des chemins racine-relatifs.

Cartes et Badges (le PM tient particulièrement à la fidélité)

Chaque <Card> sur une page d'index devrait porter les mêmes badges de portée/statut que ceux présents dans la documentation Sphinx originale sous docs/. Correspondance :

Intentions valides : success, note, tip, warning, error, info, launch, check. Placez les badges comme dernière ligne à l'intérieur du <Card>, séparés par une ligne vierge du texte du corps. Le CSS dans main.css (.fern-card .fern-docs-badge) gère l'espacement vertical par rapport à la description et l'espacement horizontal entre les badges adjacents — n'ajoutez pas de props style= inline.

<Cards>
  <Card title="Quickstart" href="/latest/get-started/quickstart">
    Install, start servers, and collect your first rollouts in one page.

    <Badge intent="success" minimal outlined>start here</Badge> <Badge minimal outlined>5 min</Badge>
  </Card>
</Cards>

Quand vous ajoutez ou éditez une Card, vérifiez le fichier docs/<same-path>/index.md original pour les badges qui étaient sur la directive :::{grid-item-card} correspondante et reproduisez-les. Supprimer silencieusement les badges est une régression.

Champs de Frontmatter

---
title: "<Page Title>"        # obligatoire — utilisé pour la nav et <h1>
description: ""              # obligatoire (peut être une chaîne vide) — SEO
position: 1                  # optionnel — ordonne les pages auto-découvertes dans un dossier
---

Le corps MDX devrait quand même s'ouvrir avec # <Page Title> correspondant au titre du frontmatter. Les dossiers utilisant title-source: frontmatter dans la YAML de version tirent l'étiquette de nav de title:.

Valider

Configuration première fois : authentifiez le CLI contre l'org Fern nvidia via Google SSO (une seule fois, flux navigateur) :

npx -y fern-api@latest login    # ouvre le navigateur → connectez-vous avec votre compte Google @nvidia.com

Exécutez depuis fern/ (aucune étape d'installation — les scripts invoquent npx -y fern-api@latest) :

npm run check       # `fern check` — validation YAML + frontmatter
npm run dev         # `fern docs dev` — aperçu localhost:3000 avec hot-reload

fern check doit réussir avant le commit. Les avertissements de liens cassés du serveur de dev pour les liens inter-versions comme /latest/about sont des faux positifs — le validateur local de Fern ne résout pas le slug de version de docs.yml par rapport à latest.yml. Le site publié les affiche correctement.

Pour régénérer la référence de librairie autodoc (gitignorée sous product-docs/) :

npm run generate:library    # `fern docs md generate`

Commit & Aperçu

git add fern/
git commit -s -m "docs: <add|update|remove> <page-title>"

Les PR qui touchent fern/** obtiennent une URL d'aperçu Fern automatique postée en commentaire par .github/workflows/fern-docs-preview-comment.yml. Aucune étape manuelle n'est nécessaire.

                    ┌─ fern-docs-ci.yml                  → fern check
PR (touche fern/) ──┼─ fern-docs-preview-build.yml       → upload artefact fern/ (pas de secrets)
                    └─ fern-docs-preview-comment.yml     → 🌿 commentaire d'URL d'aperçu

Push vers main (touche docs/** ou fern/**) → publish-fern-docs.yml → docs.nvidia.com/nemo/gym
Tag push (docs/v*)                         → publish-fern-docs.yml → docs.nvidia.com/nemo/gym
Manual dispatch                            → publish-fern-docs.yml → docs.nvidia.com/nemo/gym

Les jobs preview-comment + publish requièrent le secret DOCS_FERN_TOKEN du dépôt ou de l'organisation (depuis fern token).

Publication en Production

Les publications en production déclenchent sur trois événements (voir .github/workflows/publish-fern-docs.yml) :

1. Push vers main quand docs/** ou fern/** changent — staging continu.
2. Tag push correspondant à docs/v* — version de release.
3. Manual dispatch depuis l'onglet Actions.

Le format du tag doit être docs/v<MAJOR>.<MINOR>.<PATCH>. Ne poussez pas un tag sauf si l'utilisateur le demande.

git tag docs/v0.3.0
git push origin docs/v0.3.0

URL → correspondance de version :

docs.nvidia.com/nemo/gym/latest/...   → branche latest
docs.nvidia.com/nemo/gym/v0.2/...     → branche 0.2

Créer une Nouvelle Branche de Version

Quand l'utilisateur expédie une nouvelle version (par ex. v0.3) :

1. Copiez fern/versions/latest/pages/ → fern/versions/v0.3/pages/ (snapshot figé du précédent « latest »).
2. Copiez fern/versions/latest.yml → fern/versions/v0.3.yml et réécrivez tous les préfixes de chemin ./latest/ en ./v0.3/.
3. Remplacez les préfixes de lien /latest/ dans le MDX du corps des nouvelles v0.3/pages/ par /v0.3/.
4. Ajoutez la version à la liste versions: de fern/docs.yml avec slug: v0.3 et availability: stable. Gardez l'entrée latest pointant vers versions/latest.yml.
5. latest/pages/ continue de progresser comme la branche dev actuelle.
6. Taguez docs/v0.3.0 et poussez pour publier.

Débogage

Références Clés