diff --git a/docs/Makefile b/docs/Makefile index 1cc55f2aa..267273e40 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,15 +1,26 @@ # Makefile for Sphinx documentation +# +# Uses `uv run` which automatically manages the virtual environment. +# No manual venv setup required. Works on Windows, macOS, and Linux. -# Default target shows help .DEFAULT_GOAL := help -.PHONY: help docs-html docs-clean docs-live docs-publish ensure-docs-env check-uv +.PHONY: help docs-html docs-clean docs-live docs-publish check-uv + +# Detect OS for cross-platform compatibility +ifeq ($(OS),Windows_NT) + RM_CMD = if exist _build rmdir /s /q _build + CHECK_UV = @where uv >nul 2>&1 || (echo. && echo uv is not installed. Install from: https://docs.astral.sh/uv/getting-started/installation/ && exit /b 1) +else + RM_CMD = rm -rf _build + CHECK_UV = @command -v uv >/dev/null 2>&1 || { echo ""; echo "❌ uv is not installed. Install from: https://docs.astral.sh/uv/getting-started/installation/"; echo ""; exit 1; } +endif # Help target help: ## Show this help message @echo "" - @echo "📚 Documentation Build System" - @echo "==============================" + @echo "Documentation Build System" + @echo "==========================" @echo "" @echo "Available targets:" @echo " make docs-html Build HTML documentation" @@ -17,134 +28,23 @@ help: ## Show this help message @echo " make docs-publish Build for publication (fail on warnings)" @echo " make docs-clean Clean built documentation" @echo "" - @echo "Note: Environment is automatically set up on first run." - @echo "" - -# Detect OS for cross-platform compatibility -ifeq ($(OS),Windows_NT) - VENV_PYTHON = ../.venv-docs/Scripts/python.exe - VENV_ACTIVATE = ..\\.venv-docs\\Scripts\\activate - VENV_ACTIVATE_PS = ..\\.venv-docs\\Scripts\\Activate.ps1 - RM_CMD = if exist _build rmdir /s /q _build - ECHO_BLANK = @echo. -else - VENV_PYTHON = ../.venv-docs/bin/python - VENV_ACTIVATE = source ../.venv-docs/bin/activate - RM_CMD = rm -rf _build - ECHO_BLANK = @echo "" -endif # Check if uv is installed check-uv: -ifeq ($(OS),Windows_NT) - @where uv >nul 2>&1 || ( \ - echo. && \ - echo ❌ uv is not installed or not in PATH && \ - echo. && \ - echo Please install uv: https://docs.astral.sh/uv/getting-started/installation/ && \ - exit 1 \ - ) -else - @command -v uv >/dev/null 2>&1 || ( \ - echo ""; \ - echo "❌ uv is not installed or not in PATH"; \ - echo ""; \ - echo "Please install uv: https://docs.astral.sh/uv/getting-started/installation/"; \ - echo ""; \ - exit 1; \ - ) -endif - -# Ensure docs environment exists and is up to date -ensure-docs-env: check-uv - @if [ ! -f "$(VENV_PYTHON)" ]; then \ - echo "📦 Setting up docs environment with uv..."; \ - cd .. && uv venv .venv-docs && uv pip install --group docs --python .venv-docs; \ - echo "✅ Environment ready!"; \ - fi + $(CHECK_UV) -docs-html: ensure-docs-env +docs-html: check-uv @echo "Building HTML documentation..." - $(VENV_PYTHON) -m sphinx -b html . _build/html + cd .. && uv run --group docs sphinx-build -b html docs docs/_build/html -docs-publish: ensure-docs-env +docs-publish: check-uv @echo "Building HTML documentation for publication (fail on warnings)..." - $(VENV_PYTHON) -m sphinx --fail-on-warning --builder html . _build/html + cd .. && uv run --group docs sphinx-build --fail-on-warning -b html docs docs/_build/html docs-clean: @echo "Cleaning built documentation..." $(RM_CMD) -docs-live: ensure-docs-env +docs-live: check-uv @echo "Starting live-reload server (sphinx-autobuild)..." - $(VENV_PYTHON) -m sphinx_autobuild --port 8001 . _build/html - @echo "Setting up docs virtual environment with uv..." -ifeq ($(OS),Windows_NT) - @where uv >nul 2>&1 || ( \ - echo. && \ - echo ❌ uv is not installed or not in PATH && \ - echo. && \ - echo uv is a fast Python package installer and resolver. && \ - echo Please install it using one of the following methods: && \ - echo. && \ - echo 🪟 Windows PowerShell: && \ - echo powershell -c "irm https://astral.sh/uv/install.ps1 | iex" && \ - echo. && \ - echo 📦 pip: && \ - echo pip install uv && \ - echo. && \ - echo 🍺 Scoop: && \ - echo scoop install uv && \ - echo. && \ - echo After installation, you may need to: && \ - echo 1. Restart your terminal && \ - echo 2. Or add uv to your PATH manually && \ - echo 3. Then run 'make docs-env' again && \ - echo. && \ - echo For more installation options, visit: https://docs.astral.sh/uv/getting-started/installation/ && \ - exit 1 \ - ) -else - @command -v uv >/dev/null 2>&1 || ( \ - echo ""; \ - echo "❌ uv is not installed or not in PATH"; \ - echo ""; \ - echo "uv is a fast Python package installer and resolver."; \ - echo "Please install it using one of the following methods:"; \ - echo ""; \ - echo "🐧 Linux/Unix:"; \ - echo " curl -LsSf https://astral.sh/uv/install.sh | sh"; \ - echo ""; \ - echo "🍺 Homebrew (macOS):"; \ - echo " brew install uv"; \ - echo ""; \ - echo "📦 pip:"; \ - echo " pip install uv"; \ - echo ""; \ - echo "After installation, you may need to:"; \ - echo "1. Restart your terminal or run: source ~/.bashrc (or ~/.zshrc)"; \ - echo "2. Or add uv to your PATH manually"; \ - echo "3. Then run 'make docs-env' again"; \ - echo ""; \ - echo "For more installation options, visit: https://docs.astral.sh/uv/getting-started/installation/"; \ - exit 1; \ - ) -endif - @echo "✅ uv found, creating virtual environment..." - cd .. && uv venv .venv-docs - cd .. && uv pip install --group docs --python .venv-docs - $(ECHO_BLANK) - @echo "✅ Documentation environment setup complete!" - $(ECHO_BLANK) - @echo "📝 Note: The environment is NOT automatically activated." - @echo "To manually activate the docs environment, run:" -ifeq ($(OS),Windows_NT) - @echo " For Command Prompt: $(VENV_ACTIVATE)" - @echo " For PowerShell: $(VENV_ACTIVATE_PS)" -else - @echo " $(VENV_ACTIVATE)" -endif - $(ECHO_BLANK) - @echo "Once activated, you can run other docs commands like:" - @echo " make docs-html # Build HTML documentation" - @echo " make docs-live # Start live-reload server" + cd .. && uv run --group docs sphinx-autobuild --port 8001 docs docs/_build/html diff --git a/docs/conf.py b/docs/conf.py index 7a4dec621..9ca1a2c69 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -113,31 +113,31 @@ # https://documatt.com/sphinx-reredirects/ # # Use this to create redirects when pages are moved or renamed. -# Format: "old/path.html": "new/path.html" +# Format: "old/path.html": "target-relative-to-source.html" # -# Examples: -# - Simple redirect: "old-page.html": "new-page.html" -# - Directory redirect: "old-dir/page.html": "new-dir/page.html" +# IMPORTANT: Target paths are RELATIVE to the source file's directory! +# - Same directory: "dir/old.html": "new.html" +# - Cross directory: "old-dir/page.html": "../new-dir/page.html" # - External redirect: "old-page.html": "https://example.com/new-page" # -# Note: Paths are relative to the HTML output directory. # The .html extension is required for source paths. redirects = { - # Get Started section renames - "get-started/setup-installation.html": "get-started/detailed-setup.html", + # Get Started section renames (same directory) + "get-started/setup-installation.html": "detailed-setup.html", # RL Framework Integration moved from training/ to contribute/ - "training/rl-framework-integration/index.html": "contribute/rl-framework-integration/index.html", - "training/rl-framework-integration/gym-integration-footprint-and-form-factor.html": "contribute/rl-framework-integration/gym-integration-footprint-and-form-factor.html", - "training/rl-framework-integration/gym-rl-framework-integration-success-criteria.html": "contribute/rl-framework-integration/gym-rl-framework-integration-success-criteria.html", - "training/rl-framework-integration/generation-backend-and-openai-compatible-http-server.html": "contribute/rl-framework-integration/generation-backend-and-openai-compatible-http-server.html", - "training/rl-framework-integration/openai-compatible-http-server-on-policy-correction.html": "contribute/rl-framework-integration/openai-compatible-http-server-on-policy-correction.html", + # Source is in training/rl-framework-integration/, target is in contribute/rl-framework-integration/ + "training/rl-framework-integration/index.html": "../../contribute/rl-framework-integration/index.html", + "training/rl-framework-integration/gym-integration-footprint-and-form-factor.html": "../../contribute/rl-framework-integration/gym-integration-footprint-and-form-factor.html", + "training/rl-framework-integration/gym-rl-framework-integration-success-criteria.html": "../../contribute/rl-framework-integration/gym-rl-framework-integration-success-criteria.html", + "training/rl-framework-integration/generation-backend-and-openai-compatible-http-server.html": "../../contribute/rl-framework-integration/generation-backend-and-openai-compatible-http-server.html", + "training/rl-framework-integration/openai-compatible-http-server-on-policy-correction.html": "../../contribute/rl-framework-integration/openai-compatible-http-server-on-policy-correction.html", # Alternate naming conventions for the same pages - "training/rl-framework-integration/integration-footprint.html": "contribute/rl-framework-integration/gym-integration-footprint-and-form-factor.html", - "training/rl-framework-integration/on-policy-corrections.html": "contribute/rl-framework-integration/openai-compatible-http-server-on-policy-correction.html", - # About/Concepts section renames - "about/concepts/core-abstractions.html": "about/concepts/core-components.html", - "about/concepts/configuration-system.html": "about/concepts/configuration.html", - # Top-level page moves + "training/rl-framework-integration/integration-footprint.html": "../../contribute/rl-framework-integration/gym-integration-footprint-and-form-factor.html", + "training/rl-framework-integration/on-policy-corrections.html": "../../contribute/rl-framework-integration/openai-compatible-http-server-on-policy-correction.html", + # About/Concepts section renames (same directory) + "about/concepts/core-abstractions.html": "core-components.html", + "about/concepts/configuration-system.html": "configuration.html", + # Top-level page moves (from root to reference/) "how-to-faq.html": "reference/faq.html", } diff --git a/docs/project.json b/docs/project.json index 02b5cce7e..8e4d65b90 100644 --- a/docs/project.json +++ b/docs/project.json @@ -1 +1,4 @@ -{"name": "nemo-gym", "version": "0.1.0"} +{ + "name": "nemo-gym", + "version": "0.1.1" +} \ No newline at end of file diff --git a/uv.lock b/uv.lock index 2f2697bdf..afb2bfd83 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 2 +revision = 3 requires-python = ">=3.12" resolution-markers = [ "python_full_version >= '3.13'", @@ -1936,6 +1936,7 @@ docs = [ { name = "sphinx-autodoc2" }, { name = "sphinx-copybutton" }, { name = "sphinx-design" }, + { name = "sphinx-reredirects" }, { name = "sphinxcontrib-mermaid" }, { name = "swagger-plugin-for-sphinx" }, ] @@ -1981,6 +1982,7 @@ docs = [ { name = "sphinx-autodoc2", specifier = ">=0.5.0" }, { name = "sphinx-copybutton", specifier = ">=0.5.2" }, { name = "sphinx-design", specifier = ">=0.6.1" }, + { name = "sphinx-reredirects", specifier = ">=0.1.6" }, { name = "sphinxcontrib-mermaid", specifier = ">=1.0.0" }, { name = "swagger-plugin-for-sphinx", specifier = ">=6.0.0" }, ] @@ -3296,6 +3298,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/c6/43/65c0acbd8cc6f50195a3a1fc195c404988b15c67090e73c7a41a9f57d6bd/sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c", size = 2215338, upload-time = "2024-08-02T13:48:42.106Z" }, ] +[[package]] +name = "sphinx-reredirects" +version = "1.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/72/61/d3039bc2b688c73e81f515afe771b7cc9631dfef63b3e3ac3aab3d73c685/sphinx_reredirects-1.0.0.tar.gz", hash = "sha256:7c9bada9f1330489fcf4c7297a2d6da2a49ca4877d3f42d1388ae1de1019bf5c", size = 711970, upload-time = "2025-05-31T14:45:55.428Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2a/7f/adb886a3db417a2ccea6a13dcb4b88d08f82104aed17e347346f79480a5f/sphinx_reredirects-1.0.0-py3-none-any.whl", hash = "sha256:1d0102710a8f633c6c885f940f440f7195ada675c1739976f0135790747dea06", size = 6173, upload-time = "2025-05-31T14:45:53.014Z" }, +] + [[package]] name = "sphinxcontrib-applehelp" version = "2.0.0"