meta-pytorch · allenwang28 · Sep 24, 2025 · Sep 22, 2025 · Sep 23, 2025 · Sep 23, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,111 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup conda env
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          auto-update-conda: true
+          miniconda-version: "latest"
+          activate-environment: test
+          python-version: '3.10'
+          auto-activate-base: false
+      - name: Verify conda environment
+        shell: bash -l {0}
+        run: |
+          conda info
+          which python
+          which conda
+      - name: Update pip
+        shell: bash -l {0}
+        run: python -m pip install --upgrade pip
+      - name: Install pytorch
+        shell: bash -l {0}
+        run: python -m pip install torch==2.9.0.dev20250826 --extra-index-url https://download.pytorch.org/whl/nightly/cpu
+      - name: Install monarch
+        shell: bash -l {0}
+        run: python -m pip install monarch-no-torch==0.1.0.dev20250826 --find-links assets/ci
+      - name: Install torchforge
+        shell: bash -l {0}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./scripts/install.sh
+      - name: Install docs dependencies
+        shell: bash -l {0}
+        run: python -m pip install -r docs/requirements.txt
+      - name: Build docs
+        shell: bash -l {0}
+        working-directory: docs
+        run: make html --keep-going SPHINXOPTS='-W'
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: docs/build/html/
+
+  # doc-preview:
+  #   runs-on: [ubuntu-latest]
+  #   needs: build-docs
+  #   if: ${{ github.event_name == 'pull_request' }}
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@v4
+  #     - name: Download artifact
+  #       uses: actions/download-artifact@v4
+  #       with:
+  #         name: docs
+  #         path: docs
+  #     - name: Add noindex to preview docs
+  #       run: |
+  #         echo "Adding noindex meta tag to prevent search engine indexing of preview docs"
+  #         find docs -name "*.html" -print0 | xargs -0 sed -i 's/<head>/<head>\n  <meta name="robots" content="noindex">/'
+  #     - name: Upload docs preview
+  #       uses: seemethere/upload-artifact-s3@v5
+  #       if: ${{ github.event_name == 'pull_request' }}
+  #       with:
+  #         retention-days: 14
+  #         s3-bucket: doc-previews
+  #         if-no-files-found: error
+  #         path: docs
+  #         s3-prefix: meta-pytorch/forge/${{ github.event.pull_request.number }}
+
+  deploy-docs:
+        needs: build-docs
+        if: github.ref == 'refs/heads/main'
+        permissions:
+          pages: write
+          id-token: write
+        environment:
+          name: github-pages
+          url: ${{ steps.deployment.outputs.page_url }}
+        runs-on: ubuntu-latest
+        steps:
+          - name: Download build artifact
+            uses: actions/download-artifact@v4
+            with:
+              name: docs
+              path: .
+
+          - name: Upload Pages artifact
+            uses: actions/upload-pages-artifact@v3
+            with:
+              path: .
+
+          - name: Deploy to GitHub Pages
+            id: deployment
+            uses: actions/deploy-pages@v4
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,25 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+# 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     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,7 @@
+sphinx==7.2.6
+-e git+https://github.com/pytorch/pytorch_sphinx_theme.git@pytorch_sphinx_theme2#egg=pytorch_sphinx_theme2
+docutils>=0.18.1,<0.21
+sphinx-design==0.6.1
+sphinxcontrib-mermaid==1.0.0
+myst-parser #==0.18.1  # if want to contribute in markdown
+sphinx-sitemap==2.7.1
diff --git a/docs/source/api.md b/docs/source/api.md
@@ -0,0 +1,35 @@
+# API Reference
+
+This section provides comprehensive API documentation for TorchForge modules and classes.
+
+TorchForge is organized into several key modules, each providing specialized functionality for post-training generative AI models:
+
+## Module Overview
+
+**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
+
+**Data Management**
+- [Data](api_data.md) - Data handling utilities, datasets, and data models
+
+**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
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+api_core
+api_actors
+api_data
+api_losses
+api_envs
+api_controller
+api_util
+```
diff --git a/docs/source/api_actors.md b/docs/source/api_actors.md
@@ -0,0 +1,19 @@
+# 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.
diff --git a/docs/source/api_controller.md b/docs/source/api_controller.md
@@ -0,0 +1,3 @@
+# Controller
+
+Distributed training orchestration and resource management components for TorchForge.
diff --git a/docs/source/api_core.md b/docs/source/api_core.md
@@ -0,0 +1,3 @@
+# Core Interfaces
+
+This section covers the fundamental interfaces and type definitions that form the foundation of TorchForge.
diff --git a/docs/source/api_data.md b/docs/source/api_data.md
@@ -0,0 +1,16 @@
+# Data Management
+
+Comprehensive data handling utilities for training and
+inference, including datasets, data models, and various
+data processing utilities.
+
+## Prompt
+
+Data model for input prompts and contexts.
+
+```{eval-rst}
+.. automodule:: forge.data_models.prompt
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
diff --git a/docs/source/api_envs.md b/docs/source/api_envs.md
@@ -0,0 +1,8 @@
+# Environments
+
+Training and inference environments for TorchForge models.
+
+
+## Chat Environment
+
+Chat-based environment for conversational AI training and inference.
diff --git a/docs/source/api_losses.md b/docs/source/api_losses.md
@@ -0,0 +1,11 @@
+# Losses
+
+Loss functions for reinforcement learning and supervised fine-tuning in TorchForge.
+
+## GRPO Loss
+
+Generalized Reward Policy Optimization (GRPO) loss implementation for reinforcement learning.
+
+## Reinforce Loss
+
+Reinforce algorithm loss implementation for policy gradient methods.
diff --git a/docs/source/api_util.md b/docs/source/api_util.md
@@ -0,0 +1,25 @@
+# Utilities
+
+General utility functions and helpers used throughout TorchForge.
+
+## Distributed Computing
+
+Utilities for distributed training and communication.
+
+```{eval-rst}
+.. automodule:: forge.util.distributed
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
+
+## Logging
+
+Logging configuration and utilities.
+
+```{eval-rst}
+.. automodule:: forge.util.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```
diff --git a/docs/source/concepts.md b/docs/source/concepts.md
@@ -0,0 +1,4 @@
+# Concepts
+
+This guide covers the fundamental concepts and architecture behind TorchForge,
+helping you understand how the system works and how to effectively use its components.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Controller

		Distributed training orchestration and resource management components for TorchForge.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Core Interfaces

		This section covers the fundamental interfaces and type definitions that form the foundation of TorchForge.