add doc page

.gitignore

@@ -17,4 +17,7 @@ agile/data/policy/eval/**
 
 fallen_states_cache/
 
+docs/_build/
+docs/venv_docs/
+
 CLAUDE.md

docs/Makefile

@@ -0,0 +1,36 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS       ?=
+SPHINXBUILD      ?= sphinx-build
+SOURCEDIR        = .
+BUILDDIR         = _build
+
+
+# Put it first so that "make" without argument is like "make help".
+.PHONY: help Makefile
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+.PHONY: multi-docs
+multi-docs:
+	@sphinx-multiversion --verbose "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	@cp _redirect/index.html $(BUILDDIR)/index.html
+
+
+.PHONY: linkcheck
+linkcheck:
+	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
+
+
+.PHONY: livehtml
+livehtml:
+	@sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/current/html" $(SPHINXOPTS) $(O)
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)/current" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,99 @@
+# Building the Documentation
+
+This directory contains the Sphinx documentation for AGILE.
+
+## Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Quick Start
+
+```bash
+# From the repository root:
+
+# 1. Install docs dependencies
+uv pip install -r docs/requirements.txt
+
+# 2. Build the HTML docs
+cd docs
+make html
+
+# 3. Open in browser
+open _build/current/html/index.html   # macOS
+xdg-open _build/current/html/index.html   # Linux
+```
+
+## Available Make Targets
+
+| Command | Description |
+|---------|-------------|
+| `make html` | Build HTML documentation into `_build/current/html/` |
+| `make livehtml` | Start a live-reload dev server (auto-rebuilds on file changes) |
+| `make linkcheck` | Check all external links for validity |
+| `make multi-docs` | Build multi-version docs (for release publishing) |
+| `make clean` | Remove all build artifacts |
+
+## Live Preview (Recommended for Development)
+
+```bash
+cd docs
+make livehtml
+```
+
+This starts `sphinx-autobuild` at `http://127.0.0.1:8000`. It watches for file
+changes and auto-reloads the browser.
+
+## Virtual Environment Note
+
+If `sphinx-build` is installed in a virtual environment and not on your system
+PATH, set the `SPHINXBUILD` variable:
+
+```bash
+SPHINXBUILD=/path/to/.venv/bin/sphinx-build make html
+```
+
+## Project Structure
+
+```
+docs/
+├── conf.py                  # Sphinx configuration
+├── index.rst                # Landing page
+├── Makefile                 # Build commands
+├── requirements.txt         # Python dependencies for docs
+├── _ext/
+│   └── agile_doc_tools.py   # Custom Sphinx directives
+├── _redirect/
+│   └── index.html           # Redirect for multi-version builds
+├── _templates/
+│   └── versioning.html      # Sidebar version selector
+└── pages/
+    ├── getting_started.rst
+    ├── architecture.rst
+    ├── tasks.rst
+    ├── training.rst
+    ├── evaluation.rst
+    ├── sim2mujoco.rst
+    ├── pretrained_policies.rst
+    ├── data_recording.rst
+    ├── deployment.rst
+    ├── development.rst
+    ├── lessons_learned.rst
+    └── faq.rst
+```
+
+## Adding a New Page
+
+1. Create `docs/pages/your_page.rst`
+2. Add it to a `toctree` in `docs/index.rst`
+3. Optionally add a card in the landing page grid
+4. Run `make html` to verify
+
+## Custom Directives
+
+The `_ext/agile_doc_tools.py` extension provides two custom directives:
+
+- `:agile_git_clone_code_block:` — Renders a git clone command that switches
+  between internal and external URLs based on the `released` flag in `conf.py`.
+- `:agile_code_link:\`<path>\`` — Renders a clickable link to a source file on
+  GitHub, automatically using the filename as display text.

docs/_ext/agile_doc_tools.py

@@ -0,0 +1,56 @@
+# Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from typing import Any
+
+from sphinx.application import Sphinx
+
+
+def agile_git_clone_code_block(app: Sphinx, _: Any, source: list[str]) -> None:
+    """Replaces :agile_git_clone_code_block: with a git clone code block.
+
+    The output URL depends on whether we are in release or internal mode.
+    """
+
+    def replacer(_: Any) -> str:
+        release_state = app.config.agile_docs_config["released"]
+        internal_git_url = app.config.agile_docs_config["internal_git_url"]
+        external_git_url = app.config.agile_docs_config["external_git_url"]
+        if release_state:
+            git_clone_target = external_git_url
+        else:
+            git_clone_target = internal_git_url
+        return f"""
+.. code-block:: bash
+
+    git clone {git_clone_target}
+
+"""
+
+    source[0] = re.sub(r":agile_git_clone_code_block:", replacer, source[0])
+
+
+def agile_code_link(app: Sphinx, _: Any, source: list[str]) -> None:
+    """Replaces :agile_code_link:`<relative/path>` with a link to the code."""
+
+    def replacer(match: re.Match) -> str:
+        relative_path = match.group("relative_path")
+        release_state = app.config.agile_docs_config["released"]
+        internal_url = app.config.agile_docs_config["internal_code_link_base_url"]
+        external_url = app.config.agile_docs_config["external_code_link_base_url"]
+        file_name = relative_path.split("/")[-1]
+        if release_state:
+            base_url = external_url
+        else:
+            base_url = internal_url
+        return f"`{file_name} <{base_url}/blob/main/{relative_path}>`__"
+
+    source[0] = re.sub(r":agile_code_link:`<(?P<relative_path>.*)>`", replacer, source[0])
+
+
+def setup(app: Sphinx) -> None:
+    app.connect("source-read", agile_git_clone_code_block)
+    app.connect("source-read", agile_code_link)
+    app.add_config_value("agile_docs_config", {}, "env")

docs/_redirect/index.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to AGILE documentation</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+  </head>
+</html>

docs/_static/custom.css

@@ -0,0 +1,18 @@
+/* Force clean background for gallery table cells */
+table.gallery td {
+    background-color: inherit !important;
+    border: none !important;
+}
+
+table.gallery img {
+    background-color: inherit !important;
+    padding: 4px;
+    border-radius: 4px;
+}
+
+table.gallery,
+table.gallery td,
+table.gallery th {
+    border: none !important;
+    box-shadow: none !important;
+}

docs/_templates/versioning.html

@@ -0,0 +1,21 @@
+{% if versions %}
+<nav class="bd-links bd-docs-nav">
+    <div class="bd-toc-item navbar-nav">
+      <ul class="nav bd-sidenav">
+        <li class="toctree-l1 has-children" style="display: flex; justify-content: center; align-items: center; flex-direction: column;">
+          <div style="text-align:center;">
+            <label for="version-select" style="font-weight: bold; display: block;">Version</label>
+          </div>
+          <select id="version-select" class="version-dropdown" style="margin: 0 auto; display: block;" onchange="location = this.value;">
+            {%- for item in versions.branches %}
+            <option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
+            {%- endfor %}
+            {%- for item in versions.tags|reverse %}
+            <option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>{{ item.name }}</option>
+            {%- endfor %}
+          </select>
+        </li>
+      </ul>
+    </div>
+</nav>
+{% endif %}

docs/conf.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Configuration file for the Sphinx documentation builder.
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import re
+import sys
+
+# Read version from pyproject.toml so we have a single source of truth.
+_pyproject_path = os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
+with open(_pyproject_path) as f:
+    _match = re.search(r'^version\s*=\s*"([^"]+)"', f.read(), re.MULTILINE)
+    AGILE_VERSION_NUMBER = _match.group(1) if _match else "0.0.0"
+
+# Make helpers and custom extensions importable
+sys.path.insert(0, os.path.abspath("."))
+sys.path.append(os.path.abspath("_ext"))
+
+# -- Project information -----------------------------------------------------
+
+project = "AGILE"
+copyright = "2025-2026, NVIDIA"
+author = "NVIDIA"
+version = AGILE_VERSION_NUMBER
+release = AGILE_VERSION_NUMBER
+released = False
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.githubpages",
+    "sphinx_tabs.tabs",
+    "sphinx_design",
+    "sphinx_copybutton",
+    "sphinx_multiversion",
+    "sphinxcontrib.mermaid",
+    "agile_doc_tools",
+]
+
+todo_include_todos = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+templates_path = ["_templates"]
+
+exclude_patterns = [
+    "_build",
+    "_templates",
+    "_redirect",
+    "Thumbs.db",
+    ".DS_Store",
+    "venv_docs",
+]
+
+# Be picky about missing references
+nitpicky = True
+nitpick_ignore: list[tuple[str, str]] = []
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "nvidia_sphinx_theme"
+html_title = f"AGILE {AGILE_VERSION_NUMBER}"
+html_show_sphinx = False
+html_theme_options = {
+    "copyright_override": {"start": 2025},
+    "pygments_light_style": "tango",
+    "pygments_dark_style": "monokai",
+    "footer_links": {},
+    "github_url": "https://github.com/nvidia-isaac/WBC_AGILE",
+}
+
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+# Sidebar: include version dropdown
+html_sidebars = {"**": ["versioning.html", "sidebar-nav-bs"]}
+
+# -- Mermaid configuration ---------------------------------------------------
+
+mermaid_version = "11"
+
+# -- Multi-version configuration ---------------------------------------------
+
+smv_remote_whitelist = r"^.*$"
+smv_branch_whitelist = r"^(main|release/.*)$"
+smv_tag_whitelist = r"^v.*$"
+
+# -- Custom docs config (used by agile_doc_tools extension) ------------------
+
+agile_docs_config = {
+    "released": released,
+    "internal_git_url": "https://gitlab-master.nvidia.com/isaac/agile.git",
+    "external_git_url": "https://github.com/nvidia-isaac/WBC_AGILE.git",
+    "internal_code_link_base_url": "https://gitlab-master.nvidia.com/isaac/agile",
+    "external_code_link_base_url": "https://github.com/nvidia-isaac/WBC_AGILE",
+}