SphinxDocs set up

.github/workflows/doc_build.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          architecture: x64
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Dependencies
+        run: |
+          set -eux
+
+          pip install -r docs/requirements.txt
+      - name: Build Sphinx Docs
+        working-directory: docs
+        run: |
+          set -eux
+
+          make html
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html/
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: ${{ github.ref == 'refs/heads/main' }}
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/Makefile

@@ -0,0 +1,29 @@
+# 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)
+
+# Generate example documentation from Python files
+generate-examples:
+	@echo "Generating example documentation..."
+	@cd "$(SOURCEDIR)" && python GenerateExamples.py
+
+# Override html target to run generate-examples first
+html: generate-examples
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile generate-examples html
+
+# 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)

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

docs/requirements.txt

@@ -0,0 +1,13 @@
+sphinx==7.2.6
+-e git+https://github.com/pytorch/pytorch_sphinx_theme.git@pytorch_sphinx_theme2#egg=pytorch_sphinx_theme2
+sphinxcontrib.katex==0.9.10
+#breathe==4.34.0  # only if generating C++
+exhale==0.2.3  # only if generating C++ docs
+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-gallery==0.14.0  # only if hosting interactive tutorials
+sphinx-sitemap==2.7.1
+sphinxext-opengraph
+nbsphinx

docs/source/GenerateExamples.py

@@ -0,0 +1,98 @@
+import os
+
+# Configuration
+EXAMPLES_DIR = "../../examples"  # Path to examples directory
+RST_DIR = "./examples"  # Where to output RST files (relative to Sphinx source dir)
+
+
+def find_python_files(directory):
+    """Find all Python files in the directory and its subdirectories, excluding __init__.py"""
+    python_files = []
+
+    # Walk through the directory tree
+    for root, _, files in os.walk(directory):
+        for file in files:
+            if file.endswith(".py") and file != "__init__.py":
+                # Get the full path
+                full_path = os.path.join(root, file)
+                # Get the path relative to the examples directory
+                rel_path = os.path.relpath(full_path, directory)
+                python_files.append(rel_path)
+
+    return python_files
+
+
+def generate_rst_files():
+    """Generate RST files for all Python examples"""
+    # Create the output directory if it doesn't exist
+    os.makedirs(RST_DIR, exist_ok=True)
+
+    # Find all Python files
+    example_files = find_python_files(EXAMPLES_DIR)
+
+    # Generate RST files for each Python file
+    for rel_path in example_files:
+        # Create subdirectories in the RST directory if needed
+        rel_dir = os.path.dirname(rel_path)
+        if rel_dir:
+            os.makedirs(os.path.join(RST_DIR, rel_dir), exist_ok=True)
+
+        # Get the base name without extension
+        base = os.path.splitext(os.path.basename(rel_path))[0]
+
+        # Capitalize and replace underscores with spaces for nicer titles
+        title = base.replace("_", " ").title()
+
+        # Create the RST file path
+        if rel_dir:
+            rst_rel_path = os.path.join(rel_dir, f"{base}.rst")
+        else:
+            rst_rel_path = f"{base}.rst"
+
+        rst_path = os.path.join(RST_DIR, rst_rel_path)
+
+        # Write the RST file
+        with open(rst_path, "w") as f:
+            f.write(
+                f"""{title}
+{'=' * len(title)}
+
+.. literalinclude:: {os.path.join('..', EXAMPLES_DIR, rel_path)}
+   :language: python
+   :linenos:
+"""
+            )
+
+        print(f"Generated RST file for {rel_path}")
+
+    # Generate a Python examples section in the examples.rst file
+    examples_rst_path = "./examples.rst"
+    with open(examples_rst_path, "r") as f:
+        content = f.read()
+
+    # Check if the Python Examples section already exists
+    if "Python Examples" not in content:
+        # Add the Python Examples section
+        python_examples_section = """
+Python Examples
+--------------
+
+These Python scripts demonstrate how to use Monarch's APIs directly in Python code:
+
+"""
+        # Add a list of Python examples
+        for rel_path in example_files:
+            base = os.path.splitext(os.path.basename(rel_path))[0]
+            title = base.replace("_", " ").title()
+            python_examples_section += f"- **{title}**: :doc:`examples/{base}`\n"
+
+        # Append the section to the examples.rst file
+        with open(examples_rst_path, "a") as f:
+            f.write(python_examples_section)
+
+        print("Added Python Examples section to examples.rst")
+
+
+if __name__ == "__main__":
+    generate_rst_files()
+    print("RST generation complete!")

docs/source/conf.py

@@ -0,0 +1,117 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Monarch"
+copyright = "2025"
+author = ""
+release = ""
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx_design",
+    "sphinx_sitemap",
+    "sphinxcontrib.mermaid",
+    "pytorch_sphinx_theme2",
+    "sphinxext.opengraph",
+    "myst_parser",
+    "nbsphinx",
+    #'myst_nb',
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+import os
+import sys
+
+# Add the repository root to the path so Sphinx can find the notebook files
+sys.path.insert(0, os.path.abspath("."))
+sys.path.insert(0, os.path.abspath("../.."))
+import pytorch_sphinx_theme2
+
+html_theme = "pytorch_sphinx_theme2"
+html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()]
+
+ogp_site_url = "http://pytorch.org/monarch"
+ogp_image = "https://pytorch.org/assets/images/social-share.jpg"
+
+html_theme_options = {
+    "navigation_with_keys": False,
+    "analytics_id": "GTM-T8XT4PS",
+    "logo": {
+        "text": "",
+    },
+    "icon_links": [
+        {
+            "name": "X",
+            "url": "https://x.com/PyTorch",
+            "icon": "fa-brands fa-x-twitter",
+        },
+        {
+            "name": "GitHub",
+            "url": "https://github.com/pytorch-labs/monarch",
+            "icon": "fa-brands fa-github",
+        },
+        {
+            "name": "Discourse",
+            "url": "https://dev-discuss.pytorch.org/",
+            "icon": "fa-brands fa-discourse",
+        },
+        {
+            "name": "PyPi",
+            "url": "https://pypi.org/project/monarch/",
+            "icon": "fa-brands fa-python",
+        },
+    ],
+    "use_edit_page_button": True,
+    "navbar_center": "navbar-nav",
+}
+
+theme_variables = pytorch_sphinx_theme2.get_theme_variables()
+templates_path = [
+    "_templates",
+    os.path.join(os.path.dirname(pytorch_sphinx_theme2.__file__), "templates"),
+]
+
+html_context = {
+    "theme_variables": theme_variables,
+    "display_github": True,
+    "github_url": "https://github.com",
+    "github_user": "pytorch-labs",
+    "github_repo": "monarch",
+    "feedback_url": "https://github.com/pytorch-labs/monarch",
+    "github_version": "main",
+    "doc_path": "docs/source",
+    "library_links": theme_variables.get("library_links", []),
+    "community_links": theme_variables.get("community_links", []),
+    "language_bindings_links": html_theme_options.get("language_bindings_links", []),
+}
+
+# not sure if this is needed
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "html_image",
+]
+
+
+# The suffix(es) of source filenames.
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# Allow errors in notebook execution
+nbsphinx_allow_errors = True

docs/source/examples.rst

@@ -0,0 +1,29 @@
+Monarch Examples
+================
+
+Welcome to Monarch's examples! This section contains various examples demonstrating how to use Monarch for distributed execution in PyTorch.
+
+Jupyter Notebooks
+----------------
+
+These interactive tutorials demonstrate key features and use cases of Monarch, helping you understand how to leverage distributed execution for your PyTorch workloads.
+
+- **Ping Pong**: A simple demonstration of basic communication between processes in a distributed setting. This example shows how to send and receive tensors between different ranks, illustrating the fundamental building blocks of distributed computing.
+
+- **SPMD DDP**: An implementation of Single Program Multiple Data (SPMD) and Distributed Data Parallel (DDP) training with Monarch. This notebook shows how to scale your PyTorch models across multiple GPUs and nodes for faster training.
+
+Each notebook contains detailed explanations, code snippets, and comments to guide you through the implementation.
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Examples Notebooks
+
+    examples/notebooks/ping_pong
+    examples/notebooks/spmd_ddp
+
+Python Examples
+--------------
+
+These Python scripts demonstrate how to use Monarch's APIs directly in Python code:
+
+- **Grpo Actor**: :doc:`examples/grpo_actor`

docs/source/examples/grpo_actor.rst

@@ -0,0 +1,6 @@
+Grpo Actor
+==========
+
+.. literalinclude:: ../../../examples/grpo_actor.py
+   :language: python
+   :linenos:

docs/source/examples/notebooks/ping_pong.ipynb

@@ -0,0 +1 @@
+/Users/sekyonda/Documents/GitHub/monarch/examples/notebooks/ping_pong.ipynb

docs/source/examples/notebooks/spmd_ddp.ipynb

@@ -0,0 +1 @@
+/Users/sekyonda/Documents/GitHub/monarch/examples/notebooks/spmd_ddp.ipynb