Documentation Development#

Build the Documentation#

The following sections describe how to set up and build the NeMo RL documentation.

Switch to the documentation source folder and generate HTML output.

cddocs/uvrun--groupdocssphinx-build._build/html

  • The resulting HTML files are generated in a_build/html folder that is created under the projectdocs/ folder.

  • The generated python API docs are placed inapidocs under thedocs/ folder.

Checking for Broken Links#

To check for broken http links in the docs, run this command:

cddocs/uvrun--groupdocssphinx-build--builderlinkcheck._build/linkcheck

It will output a JSON file at_build/linkcheck/output.json with links it found while building thedocs. Records will have a status ofbroken if the link is not reachable. Thedocs/conf.py file isconfigured to ignore github links because the CI test will often experience rate limit errors.Comment out thelinkcheck_ignore variable there to check all the links.

Live Building#

When writing documentation, it can be helpful to serve the documentation and have it update live while you edit.

To do so, run:

cddocs/uvrun--groupdocssphinx-autobuild._build/html--port12345--host0.0.0.0

Open a web browser and go tohttp://${HOST_WHERE_SPHINX_COMMAND_RUN}:12345 to view the output.

Run Tests in Python Docstrings#

We also run tests in our Python docstrings. You can run them with:

cddocs/uvrun--groupdocssphinx-build-bdoctest._build/doctest

Write Tests in Python Docstrings#

Any code in triple backtick blocks with the{doctest} directive will be tested. The format follows Python’s doctest module syntax, where>>> indicates Python input and the following line shows the expected output. Here’s an example:

defadd(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    ```    """returnx+y

Documentation Version#

The three files below control the version switcher. Before you attempt to publish a new version of the documentation, update these files to match the latest version numbers.

  • docs/versions1.json

  • docs/project.json

  • docs/conf.py