WIP Automate docs venv setup

docs/README.md

@@ -1,36 +1,104 @@
-# `isaaclab_arena` Dox - Developer Guide
+# `isaaclab_arena` Docs - Developer Guide
 
-To build the `isaaclab_arena` docs locally follow the following instructions.
+To build the `isaaclab_arena` docs locally follow the instructions below.
 
-Enter the `isaaclab_arena` docker.
+## Quick Start (Automated Setup with Activation)
 
-```
+1. Enter the `isaaclab_arena` docker:
+
+```bash
 ./docker/run_docker.sh
 ```
 
-The version of sphinx that we use requires a newer version of python.
-Install a newer version of `python` and `venv`:
+2. Run the setup script (one-time setup) - **use `source` to activate the environment**:
 
+```bash
+source ./docs/setup.sh
 ```
-sudo apt-get install python3.11 python3.11-venv
+
+This will:
+- Install Python 3.11 and venv
+- Create a virtual environment at `docs/venv_docs/`
+- Install all documentation dependencies
+- **Activate the environment in your current shell** ✨
+
+You'll see `(venv_docs)` in your prompt, indicating the environment is active.
+
+3. Build the documentation:
+
+```bash
+cd docs
+make html
 ```
 
-> It looks like this actually overwrites the currently installed version of python
-> inside.
+4. View the docs by opening: `docs/_build/html/index.html`
+
+### Reactivating Later
 
-Create a `venv` and install the dependencies
+If you exit your shell or want to work on docs again:
 
+```bash
+cd docs
+source venv_docs/bin/activate  # Activates environment
+make html                        # Build docs
 ```
+
+## Manual Setup (Alternative)
+
+If you prefer manual setup:
+
+```bash
+# Install Python 3.11
+sudo apt-get install python3.11 python3.11-venv
+
+# Create virtual environment
+cd docs
 python3.11 -m venv venv_docs
+
+# Activate and install dependencies
 source venv_docs/bin/activate
-cd ./docs
 python3.11 -m pip install -r requirements.txt
+
+# Build docs
+make html
 ```
 
-Make the docs
+## Available Scripts
 
-```
+After initial setup, you have multiple options:
+
+### Option 1: Manual build (with active environment)
+```bash
+cd docs
+source venv_docs/bin/activate  # If not already active
 make html
 ```
 
-To view the docs, navigationl to `isaaclab_arena/docs/_build/html/index.html`, and double-click.
+### Option 2: Automated build script (no activation needed)
+```bash
+./docs/build.sh  # Builds without requiring activation
+```
+
+### Option 3: Full setup script (non-activating)
+```bash
+./docs/setup_and_build.sh  # Sets up and installs but doesn't activate
+```
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `source ./docs/setup.sh` | **Setup + activate** (one command setup with activation) |
+| `./docs/setup_and_build.sh` | Setup only (doesn't activate) |
+| `./docs/build.sh` | Build docs (no activation needed) |
+| `source docs/venv_docs/bin/activate` | Manually activate environment |
+| `deactivate` | Deactivate the virtual environment |
+| `make html` | Build docs (requires active environment) |
+| `make clean` | Clean previous builds |
+
+## Notes
+
+- The sphinx version requires Python 3.11+
+- The virtual environment only needs to be created once
+- Use `source` (not `./`) to run scripts that need to activate the environment
+- Use `deactivate` to exit the virtual environment when done

docs/setup.sh

@@ -0,0 +1,86 @@
+# Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# Setup documentation environment for isaaclab_arena
+#
+# USAGE: source ./docs/setup.sh
+# This will set up the environment AND activate it in your current shell
+
+# Detect if script is being sourced or executed
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    echo "❌ Error: This script must be sourced, not executed!"
+    echo ""
+    echo "Please run:"
+    echo "  source ./docs/setup.sh"
+    echo ""
+    echo "Or from the docs directory:"
+    echo "  source setup.sh"
+    exit 1
+fi
+
+# Get the directory where this script is located
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$SCRIPT_DIR"
+
+echo "=========================================="
+echo "Isaac Lab Arena - Documentation Setup"
+echo "=========================================="
+echo ""
+
+# Check if we're in docker (optional warning)
+if [ ! -f "/.dockerenv" ]; then
+    echo "⚠️  Warning: It appears you're not running inside the Docker container."
+    echo "   Consider running: ./docker/run_docker.sh"
+    echo ""
+fi
+
+# Step 1: Install Python 3.11 and venv
+echo "Step 1/4: Checking Python 3.11 and venv..."
+if ! command -v python3.11 &> /dev/null; then
+    echo "  Installing python3.11 and python3.11-venv..."
+    sudo apt-get update -qq
+    sudo apt-get install -y -qq python3.11 python3.11-venv
+    echo "  ✓ Python 3.11 installed"
+else
+    echo "  ✓ Python 3.11 already installed"
+fi
+echo ""
+
+# Step 2: Create virtual environment if it doesn't exist
+echo "Step 2/4: Setting up virtual environment..."
+if [ ! -d "venv_docs" ]; then
+    echo "  Creating new virtual environment..."
+    python3.11 -m venv venv_docs
+    echo "  ✓ Virtual environment created"
+else
+    echo "  ✓ Virtual environment already exists"
+fi
+echo ""
+
+# Step 3: Activate the virtual environment
+echo "Step 3/4: Activating virtual environment..."
+source venv_docs/bin/activate
+echo "  ✓ Virtual environment activated"
+echo ""
+
+# Step 4: Install/update dependencies
+echo "Step 4/4: Installing documentation dependencies..."
+python -m pip install --upgrade pip -q
+python -m pip install -r requirements.txt -q
+echo "  ✓ Dependencies installed"
+echo ""
+
+echo "=========================================="
+echo "✓ Setup complete and environment active!"
+echo "=========================================="
+echo ""
+echo "Your shell now has the (venv_docs) environment active."
+echo ""
+echo "Build the docs with:"
+echo "  make html"
+echo ""
+echo "To deactivate the environment later:"
+echo "  deactivate"
+echo ""
+echo "To reactivate in the future:"
+echo "  cd docs && source venv_docs/bin/activate"
+echo ""