Add basic API docs

.github/workflows/docs.yml

@@ -39,7 +39,7 @@ jobs:
         run: python -m pip install torch==2.9.0 --index-url https://download.pytorch.org/whl/test/cu130
       - name: Install monarch
         shell: bash -l {0}
-        run: python -m pip install monarch-no-torch==0.1.0.dev20250826 --find-links assets/ci
+        run: pip install torchmonarch
       - name: Install torchforge
         shell: bash -l {0}
         env:
@@ -52,9 +52,35 @@ jobs:
         shell: bash -l {0}
         working-directory: docs
         run: |
-          set +e  # Don't exit on error
-          make html SPHINXOPTS="-WT --keep-going" || echo "Build completed with warnings/errors"
-          set -e  # Re-enable exit on error for subsequent commands
+          # Set up library paths to ensure all dependencies are available
+          # This is critical for monarch and other native dependencies that need libpython3.10.so.1.0
+          export LD_LIBRARY_PATH="${CONDA_PREFIX}/lib:${LD_LIBRARY_PATH:-}"
+
+          # Also set CUDA paths if needed
+          if [ -d "/usr/local/cuda-12.9" ]; then
+            export LD_LIBRARY_PATH="/usr/local/cuda-12.9/compat:${LD_LIBRARY_PATH}"
+            export CUDA_HOME=/usr/local/cuda-12.9
+          fi
+
+          # Verify dependencies can be imported before building docs
+          echo "Verifying dependencies..."
+          python -c "import forge; print('✓ forge imported successfully')"
+          python -c "import monarch; print('✓ monarch imported successfully')"
+
+          # Build docs with -WT (warnings as errors) and --keep-going to see all issues
+          # Capture exit code but continue to see all errors
+          set +e
+          make html SPHINXOPTS="--keep-going"
+          BUILD_EXIT_CODE=$?
+          set -e
+
+          # Report results
+          if [ $BUILD_EXIT_CODE -ne 0 ]; then
+            echo "❌ Documentation build failed with warnings or errors (exit code: $BUILD_EXIT_CODE)"
+            exit $BUILD_EXIT_CODE
+          else
+            echo "✅ Documentation build completed successfully with no warnings or errors"
+          fi
       - name: Upload docs artifact
         uses: actions/upload-artifact@v4
         with:

.gitignore

@@ -153,7 +153,7 @@ docs/source/generated_examples/
 docs/source/gen_modules/
 docs/source/generated/
 docs/source/sg_execution_times.rst
-docs/source/tutorials
+docs/source/tutorials/*
 # pytorch-sphinx-theme gets installed here
 docs/src
 

docs/requirements.txt

@@ -6,3 +6,4 @@ sphinxcontrib-mermaid==1.0.0
 sphinx-gallery==0.19.0
 myst-parser #==0.18.1  # if want to contribute in markdown
 sphinx-sitemap==2.7.1
+sphinx-autodoc-typehints==1.25.3

docs/source/_static/custom.css

@@ -0,0 +1,98 @@
+/* Custom CSS for collapsible parameter lists */
+
+/* Hide parameters in signatures */
+.sig-param-hidden {
+    display: none !important;
+}
+
+/* Inline toggle button for signatures */
+.params-toggle-btn-inline {
+    display: inline;
+    padding: 0.2rem 0.5rem;
+    margin: 0 0.25rem;
+    background-color: var(--pst-color-background);
+    border: 1px solid var(--pst-color-border);
+    border-radius: 3px;
+    cursor: pointer;
+    font-size: 0.85em;
+    font-family: var(--pst-font-family-base);
+    color: var(--pst-color-primary);
+    transition: all 0.2s ease;
+    vertical-align: middle;
+}
+
+.params-toggle-btn-inline:hover {
+    background-color: var(--pst-color-background);
+    border-color: var(--pst-color-border);
+}
+
+.params-toggle-btn-inline:focus {
+    outline: none;
+}
+
+.toggle-icon {
+    display: inline-block;
+    font-size: 0.8em;
+    transition: transform 0.2s ease;
+}
+
+/* Wrapper for the button */
+.sig-params-wrapper {
+    display: inline;
+}
+
+/* Old styles for field-list collapsing (kept for backward compatibility) */
+.collapsible-params {
+    margin: 1rem 0;
+}
+
+.params-toggle-btn {
+    display: inline-block;
+    padding: 0.5rem 1rem;
+    margin-bottom: 0.5rem;
+    background-color: var(--pst-color-background);
+    border: 1px solid var(--pst-color-border);
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 0.9rem;
+    color: var(--pst-color-primary);
+    transition: all 0.3s ease;
+}
+
+.params-toggle-btn:hover {
+    background-color: var(--pst-color-background);
+    border-color: var(--pst-color-border);
+}
+
+.params-content {
+    max-height: 10000px;
+    overflow: hidden;
+    transition: max-height 0.5s ease, opacity 0.3s ease;
+    opacity: 1;
+}
+
+.params-content.collapsed {
+    max-height: 0;
+    opacity: 0;
+}
+
+/* Ensure the collapsed parameters look good */
+.params-content dl.field-list {
+    margin-top: 0;
+}
+
+.params-content > dt {
+    margin-top: 0.5rem;
+}
+
+.params-content > dt:first-child {
+    margin-top: 0;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+    .params-toggle-btn {
+        width: 100%;
+        text-align: left;
+    }
+}

docs/source/_static/custom.js

@@ -0,0 +1,93 @@
+// Custom JavaScript to make long parameter lists in class signatures collapsible
+document.addEventListener('DOMContentLoaded', function() {
+    console.log('Collapsible parameters script loaded');
+
+    // Find all class/function signatures
+    const signatures = document.querySelectorAll('dl.py.class > dt, dl.py.function > dt, dl.py.method > dt');
+
+    signatures.forEach(function(signature) {
+        // Find all parameter elements in the signature
+        const params = signature.querySelectorAll('em.sig-param, .sig-param');
+
+        console.log(`Found signature with ${params.length} parameters`);
+
+        // Only make it collapsible if there are more than 10 parameters
+        if (params.length > 10) {
+            console.log('Creating collapsible structure for signature with', params.length, 'parameters');
+
+            const visibleCount = 5;
+            const hiddenCount = params.length - visibleCount;
+
+            // Create a wrapper div for the toggle button
+            const wrapper = document.createElement('span');
+            wrapper.className = 'sig-params-wrapper';
+            wrapper.style.display = 'inline';
+
+            // Create toggle button
+            const toggleBtn = document.createElement('button');
+            toggleBtn.className = 'params-toggle-btn-inline';
+            toggleBtn.innerHTML = `<i class="fa-solid fa-chevron-right"></i> Show More`;
+            toggleBtn.setAttribute('aria-expanded', 'false');
+            toggleBtn.title = `Show ${hiddenCount} more parameters`;
+
+            // Collect all nodes to hide (params and text nodes between them)
+            const nodesToHide = [];
+
+            // Hide parameters after the first 3
+            let insertedButton = false;
+            params.forEach(function(param, index) {
+                if (index >= visibleCount) {
+                    // Add 'hidden' class to hide the parameter
+                    param.classList.add('sig-param-hidden');
+                    nodesToHide.push(param);
+
+                    // Also hide the text node (comma/space) that follows this parameter
+                    let nextNode = param.nextSibling;
+                    while (nextNode && nextNode.nodeType === Node.TEXT_NODE) {
+                        const textSpan = document.createElement('span');
+                        textSpan.className = 'sig-param-hidden';
+                        textSpan.textContent = nextNode.textContent;
+                        nextNode.parentNode.replaceChild(textSpan, nextNode);
+                        nodesToHide.push(textSpan);
+                        break;
+                    }
+
+                    // Insert the toggle button before the first hidden parameter
+                    if (!insertedButton) {
+                        param.parentNode.insertBefore(wrapper, param);
+                        wrapper.appendChild(toggleBtn);
+                        insertedButton = true;
+                    }
+                }
+            });
+
+            // Add click handler to toggle
+            toggleBtn.addEventListener('click', function(e) {
+                e.preventDefault();
+                e.stopPropagation();
+
+                const isExpanded = toggleBtn.getAttribute('aria-expanded') === 'true';
+
+                if (isExpanded) {
+                    // Collapse: hide parameters again
+                    nodesToHide.forEach(function(node) {
+                        node.classList.add('sig-param-hidden');
+                    });
+                    toggleBtn.setAttribute('aria-expanded', 'false');
+                    toggleBtn.innerHTML = `<i class="fa-solid fa-chevron-right"></i> Show More`;
+                    toggleBtn.title = `Show ${hiddenCount} more parameters`;
+                } else {
+                    // Expand: show all parameters
+                    nodesToHide.forEach(function(node) {
+                        node.classList.remove('sig-param-hidden');
+                    });
+                    toggleBtn.setAttribute('aria-expanded', 'true');
+                    toggleBtn.innerHTML = `<i class="fa-solid fa-chevron-down"></i> Hide`;
+                    toggleBtn.title = `Hide ${hiddenCount} parameters`;
+                }
+            });
+
+            console.log('Collapsible structure created successfully');
+        }
+    });
+});

docs/source/api.md

@@ -1,35 +1,35 @@
 # API Reference
 
-This section provides comprehensive API documentation for TorchForge modules and classes.
+This section provides comprehensive API documentation for TorchForge.
 
-TorchForge is organized into several key modules, each providing specialized functionality for post-training generative AI models:
+## Overview
 
-## Module Overview
+TorchForge is a PyTorch native platform for post-training generative AI models,
+designed to streamline reinforcement learning workflows for large language
+models. The platform leverages PyTorch's distributed computing capabilities
+and is built on top of [Monarch](https://meta-pytorch.org/monarch/),
+making extensive use of actors for distributed computation and fault tolerance.
 
-**Core Components**
-- [Interfaces & Types](api_core.md) - Core interfaces and type definitions
-- [Actors](api_actors.md) - Model training and inference components
-- [Controller](api_controller.md) - Distributed training orchestration and resource management
+Key Features of TorchForge include:
 
-**Data Management**
-- [Data](api_data.md) - Data handling utilities, datasets, and data models
+- **Actor-Based Architecture**: TorchForge uses an actor-based system for distributed training, providing excellent scalability and fault tolerance.
+- **PyTorch Native**: Built natively on PyTorch, ensuring seamless integration with existing PyTorch workflows.
+- **Post-Training Focus**: Specifically designed for post-training techniques like RLHF, SFT, and other alignment methods.
+- **Distributed by Design**: Supports multi-GPU and multi-node training out of the box.
 
-**Training Components**
-- [Losses](api_losses.md) - Loss functions for reinforcement learning and supervised fine-tuning
-- [Environments](api_envs.md) - Training and inference environments
 
-**Tools & Utilities**
-- [Utilities](api_util.md) - General utility functions and helpers
+For most use cases, you'll interact with the high-level service
+interfaces, which handle the complexity of actor coordination and
+distributed training automatically.
 
-```{toctree}
-:maxdepth: 2
-:hidden:
+For advanced users who need fine-grained control, the individual actor
+APIs provide direct access to the underlying distributed components.
 
-api_core
+```{toctree}
+:maxdepth: 1
 api_actors
-api_data
-api_losses
-api_envs
-api_controller
-api_util
+api_service
+api_generator
+api_model
+api_trainer
 ```

docs/source/api_actors.md

@@ -1,19 +1,20 @@
-# Actors
-
-The actors module contains the core components for model training and inference in TorchForge. This includes policy actors, reference models, replay buffers, and trainers.
-
-## Policy Actor
-
-The policy actor is responsible for model inference and policy interactions during training.
-
-## Reference Model
-
-The reference model provides baseline comparisons for reinforcement learning algorithms.
-
-## Replay Buffer
-
-The replay buffer manages storage and sampling of training experiences.
-
-## Trainer
-
-The trainer orchestrates the training process and implements training algorithms.
+# ForgeActor
+
+```{eval-rst}
+.. currentmodule:: forge.actors
+```
+
+The actors module contains the core components for model training
+and inference in TorchForge. These pre-built actors provide essential
+functionality for reinforcement learning workflows and can be used
+as building blocks for complex distributed training systems.
+
+```{eval-rst}
+.. currentmodule:: forge.controller.actor
+
+.. autoclass:: ForgeActor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: logger, setup, set_env, __init__
+```