Développement de la Documentation

• Développement de la Documentation
  • Construire la Documentation
  • Construction en direct
  • Exécuter les Tests dans les Docstrings Python
  • Écrire des Tests dans les Docstrings Python
  • Version de la Documentation

Construire la Documentation

Les sections suivantes décrivent comment configurer et construire la documentation NeMo RL.

Basculez vers le dossier source de la documentation et générez la sortie HTML.

cd docs/
uv run --group docs sphinx-build . _build/html

• Les fichiers HTML résultants sont générés dans un dossier _build/html créé sous le dossier docs/ du projet.
• Les docs API python générés sont placés dans apidocs sous le dossier docs/.

Vérification des Liens Brisés

Pour vérifier les liens http brisés dans la documentation, exécutez cette commande :

cd docs/
uv run --group docs sphinx-build --builder linkcheck . _build/linkcheck

Il générera un fichier JSON à _build/linkcheck/output.json avec les liens trouvés lors de la construction de la documentation. Les enregistrements auront un statut broken si le lien n’est pas accessible. Le fichier docs/conf.py est configuré pour ignorer les liens github car le test CI rencontrera souvent des erreurs de limite de taux. Commentez la variable linkcheck_ignore pour vérifier tous les liens.

Construction en Direct

Lors de la rédaction de la documentation, il peut être utile de servir la documentation et de la mettre à jour en direct pendant que vous modifiez.

Pour ce faire, exécutez :

cd docs/
uv run --group docs sphinx-autobuild . _build/html --port 12345 --host 0.0.0.0

Ouvrez un navigateur web et allez à http://${HOST_WHERE_SPHINX_COMMAND_RUN}:12345 pour voir la sortie.

Exécuter les Tests dans les Docstrings Python

Nous exécutons également des tests dans nos docstrings Python. Vous pouvez les exécuter avec :

cd docs/
uv run --group docs sphinx-build -b doctest . _build/doctest

Écrire des Tests dans les Docstrings Python

Tout code dans des blocs de triple backticks avec la directive {doctest} sera testé. Le format suit la syntaxe du module doctest de Python, où >>> indique l’entrée Python et la ligne suivante montre la sortie attendue. Voici un exemple :

def add(x: int, y: int) -> int:
    """
    Adds two integers together.
    Args:
        x (int): The first integer to add.
        y (int): The second integer to add.
    Returns:
        int: The sum of x and y.
    Examples:
    ```{doctest}
    >>> from nemo_rl.made_up_package import add
    >>> add(1, 2)
    3

""" return x + y

## Version de la Documentation
Les trois fichiers ci-dessous contrôlent le sélecteur de version. Avant de tenter de publier une nouvelle version de la documentation, mettez à jour ces fichiers pour qu'ils correspondent aux derniers numéros de version.
* docs/versions1.json
* docs/project.json
* docs/conf.py