Add sphinxcontrib-katex and docs guide (#10)

* Add sphinxcontrib-katex

Signed-off-by: Charlie Truong <[email protected]>

* Add docs for building docs

Signed-off-by: Charlie Truong <[email protected]>

* Update contribution guide to include uv guideline

Signed-off-by: Charlie Truong <[email protected]>

---------

Signed-off-by: Charlie Truong <[email protected]>

Author: chtruong814

CONTRIBUTING.md

@@ -4,6 +4,37 @@
 
 Use [abseil-py](https://github.com/abseil/abseil-py/tree/main)'s **logging**, **testing** and **flags** instead of Python's own **logging**, **unittest** and **argparse**.
 
+We use [uv](https://docs.astral.sh/uv/) for managing dependencies. For reproducible builds, our project tracks the generated `uv.lock` file in the repository.
+On a weekly basis, the CI attemps an update of the lock file to test against upstream dependencies.
+
+New required dependencies can be added by `uv add $DEPENDENCY`.
+
+New optional dependencies can be added by `uv add --optional --extra $EXTRA $DEPENDENCY`.
+
+`EXTRA` refers to the subgroup of extra-dependencies to which you're adding the new dependency.
+Example: For adding a TRT-LLM specific dependency, run `uv add --optional --extra trtllm $DEPENDENCY`.
+
+New dependencies to a dependency group can be added with `uv add --group $GROUP $DEPENDENCY`. Dependency groups are specific to uv and are also optional dependencies but not intended to be used with the package such as docs dependencies.
+
+Alternatively, the `pyproject.toml` file can also be modified directly.
+
+Adding a new dependency will update UV's lock-file. Please check this into your branch:
+
+```bash
+git add uv.lock pyproject.toml
+git commit -m "build: Adding dependencies"
+git push
+```
+
+### 🧹 Linting and Formatting
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting. CI does not auto-fix linting and formatting issues, but most issues can be fixed by running the following command:
+
+```bash
+uv run ruff check --fix .
+uv run ruff format .
+```
+
 ## Coding Style
 
 We generally follow [Google's style guides](https://google.github.io/styleguide/) , with some exceptions:
@@ -16,7 +47,7 @@ We generally follow [Google's style guides](https://google.github.io/styleguide/
 
 Although common, **mixed case is not allowed** in any code.
 
-Run pre-commit at local before submitting merge request. You can also read [.pre-commit-config.yaml]( .pre-commit-config.yaml) to understand what are being forced. The **flake8** and **mypy** settings are inherited from PyTorch. 
+Run pre-commit at local before submitting merge request. You can also read [.pre-commit-config.yaml]( .pre-commit-config.yaml) to understand what are being forced. The **flake8** and **mypy** settings are inherited from PyTorch.
 
 ## Test
 
@@ -44,9 +75,9 @@ We use [abseil-py](https://github.com/abseil/abseil-py/tree/main) **testing** be
   ```
   Developer Certificate of Origin
   Version 1.1
-  
+
   Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
-  
+
   Everyone is permitted to copy and distribute verbatim copies of this
   license document, but changing it is not allowed.
 

docs/conf.py

@@ -39,6 +39,7 @@
     "sphinx.ext.doctest",  # Allows testing in docstrings
     "sphinx.ext.napoleon",  # For google style docstrings
     "sphinx_copybutton",  # For copy button in code blocks
+    "sphinxcontrib.katex",  # For KaTeX math rendering
 ]
 
 templates_path = ["_templates"]

docs/documentation.md

@@ -0,0 +1,47 @@
+# Documentation Development
+
+- [Documentation Development](#documentation-development)
+  - [Build the Documentation](#build-the-documentation)
+  - [Live Building](#live-building)
+
+
+## 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.
+
+```sh
+cd docs/
+uv run --only-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:
+
+```sh
+cd docs/
+uv run --only-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:
+
+```sh
+cd docs/
+uv run --only-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.

docs/index.md

@@ -6,5 +6,6 @@
 :caption: Development
 :hidden:
 
+documentation.md
 apidocs/index.rst
 ```

pyproject.toml

@@ -72,6 +72,7 @@ docs = [
     "sphinx-autobuild>=2024.10.3",
     "sphinx-autodoc2>=0.5.0",
     "sphinx-copybutton>=0.5.2",
+    "sphinxcontrib-katex>=0.9.11",
 ]
 test = [
     "coverage>=7.8.1",