documentation.md

Documentation Development

• Documentation Development
  • Build the Documentation
  • Live Building
  • Run Tests in Python Docstrings
  • Write Tests in Python Docstrings
  • Documentation Version

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.

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

• The resulting HTML files are generated in a _build/html folder that is created under the project docs/ folder.
• The generated python API docs are placed in apidocs under the docs/ folder.

Checking for Broken Links

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

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

It will output a JSON file at _build/linkcheck/output.json with links it found while building the docs. Records will have a status of broken if the link is not reachable. The docs/conf.py file is configured to ignore github links because the CI test will often experience rate limit errors. Comment out the linkcheck_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:

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

Open a web browser and go to http://${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:

cd docs/
uv run --group docs sphinx-build -b doctest . _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:

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

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