SphinxDocs set up

.github/workflows/doc_build.yml

@@ -0,0 +1,87 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref == 'refs/heads/main' && github.run_number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          architecture: x64
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt, clippy
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libunwind-dev
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r build-requirements.txt
+          pip install -r docs/requirements.txt
+
+      - name: Generate Rust API Documentation
+        run: |
+          # Set environment variables for CPU-only build
+          export USE_CUDA=0
+          export USE_TENSOR_ENGINE=0
+          export RUSTFLAGS="-Zthreads=16"
+          export _GLIBCXX_USE_CXX11_ABI=1
+
+          # Generate documentation for specific crates that don't depend on CUDA
+          cargo doc --no-deps -p hyperactor -p hyperactor_macros -p hyperactor_multiprocess -p hyperactor_mesh -p hyperactor_mesh_macros
+
+          # Create an index.html file in the target/doc directory to serve as the main entry point
+          echo '<meta http-equiv="refresh" content="0; url=hyperactor/index.html">' > target/doc/index.html
+
+          # Ensure the target/doc directory exists in the expected location for Sphinx
+          mkdir -p docs/source/target
+          cp -r target/doc docs/source/target/
+
+      - name: Build Sphinx Docs
+        working-directory: docs
+        run: |
+          make html
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  deploy:
+    needs: build
+    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: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -21,4 +21,14 @@ Cargo.lock
 # mdbook output
 books/hyperactor-book/book/**
 
+# macOS files
+.DS_Store
+docs/source/.DS_Store
+
+# Sphinx build files
+build/**
+docs/_build/**
+docs/build/**
+docs/generated/**
+
 CLAUDE.md

books/hyperactor-book/README.md

@@ -1,7 +1,14 @@
-# hyperactor Documentation Book
+# Hyperactor Documentation Book
 
 This is the development documentation for the hyperactor system, built using [`mdBook`](https://rust-lang.github.io/mdBook/).
 
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+./src/introduction
+```
+
 ## Running the Book
 
 ### On the **Server**

books/hyperactor-book/src/introduction.md

@@ -5,3 +5,14 @@ This book describes the design and implementation of the hyperactor runtime.
 The goal is to provide a clear, structured explanation of how actors communicate safely and efficiently across distributed systems using hyperactor’s abstractions.
 
 We hope this becomes the book we wish we had when we started working with Monarch. Work in progress.
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+refrences
+mailbox
+macros
+actors
+summary
+```

docs/Makefile

@@ -0,0 +1,35 @@
+# 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 and include books
+html:
+	@echo "Building HTML documentation with books directory..."
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile 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)
+
+clean:
+	@echo "Cleaning up build directory..."
+	@rm -rf "$(BUILDDIR)"
+	@rm -rf "$(SOURCEDIR)/generated"

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,14 @@
+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
+pillow  # Required for image processing in documentation

docs/source/books/books.md

@@ -0,0 +1,16 @@
+# Books
+
+This section contains books and comprehensive guides for Monarch.
+
+```{toctree}
+:maxdepth: 2
+:caption: Available Books
+:hidden:
+
+./hyperactor-book/src/introduction
+```
+
+
+## [HyperActor Book](./hyperactor-book/src/introduction)
+
+The HyperActor Book provides a comprehensive guide to using the actor system in Monarch.

docs/source/books/hyperactor-book/.gitignore

@@ -0,0 +1 @@
+book/

docs/source/books/hyperactor-book/README.md

@@ -0,0 +1,75 @@
+# Hyperactor Documentation Book
+
+This is the development documentation for the hyperactor system, built using [`mdBook`](https://rust-lang.github.io/mdBook/).
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+./src/introduction
+./src/refrences
+mailbox
+macros
+actors
+summary
+```
+
+## Running the Book
+
+### On the **Server**
+
+To run the book on a remote server (e.g., `devgpu004`):
+
+```bash
+x2ssh devgpu004.rva5.facebook.com
+tmux new -s mdbook
+cd ~/fbsource/fbcode/monarch/books/hyperactor-book
+mdbook serve
+```
+Then detach with Ctrl+b, then d.
+
+### On the **Client**
+
+To access the remote book from your local browser:
+```bash
+autossh -M 0 -N -L 3000:localhost:3000 devgpu004.rva5.facebook.com
+```
+Then open http://localhost:3000 in your browser.
+
+**Note**: If you don’t have autossh installed, you can install it with:
+```bash
+brew install autossh
+```
+
+### Notes
+
+- The source is located in src/, with structure defined in SUMMARY.md.
+- The book will auto-reload in the browser on edits.
+
+## Cleaning Up
+
+To shut down the book server:
+
+### Option 1: Reattach and stop
+
+```bash
+x2ssh devgpu004.rva5.facebook.com
+tmux attach -t mdbook
+```
+Inside the session:
+- Press Ctrl+C to stop mdbook serve
+- Then type exit to close the shell and terminate the tmux session
+
+### Option 2: Kill the session directly
+
+If you don’t want to reattach, you can kill the session from a new shell:
+```bash
+x2ssh devgpu004.rva5.facebook.com
+tmux kill-session -t mdbook
+```
+
+### Optional: View active tmux sessions
+```bash
+tmux ls
+```
+Use this to check whether the mdbook session is still running.

docs/source/books/hyperactor-book/book.toml

@@ -0,0 +1,9 @@
+[book]
+authors = ["Shayne Fletcher"]
+language = "en"
+src = "src"
+title = "Hyperactor Book"
+
+[output.html]
+git-repository-url = "https://github.com/pytorch-labs/monarch"
+edit-url-template = "https://github.com/pytorch-labs/monarch/edit/main/books/hyperactor-book/src/{path}"

docs/source/books/hyperactor-book/src/SUMMARY.md

@@ -0,0 +1,39 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [References](references/index.md)
+  - [Syntax](references/syntax.md)
+  - [WorldId](references/world_id.md)
+  - [ProcId](references/proc_id.md)
+  - [ActorId](references/actor_id.md)
+  - [PortId](references/port_id.md)
+  - [GangId](references/gang_id.md)
+  - [Reference](references/reference.md)
+  - [Typed References](references/typed_refs.md)
+- [Mailboxes and Routers](mailboxes/index.md)
+  - [Ports](mailboxes/ports.md)
+  - [MailboxSender](mailboxes/mailbox_sender.md)
+  - [Reconfigurable Senders](mailboxes/reconfigurable_sender.md)
+  - [MailboxServer](mailboxes/mailbox_server.md)
+  - [MailboxClient](mailboxes/mailbox_client.md)
+  - [Mailbox](mailboxes/mailbox.md)
+  - [Delivery Semantics](mailboxes/delivery.md)
+  - [Multiplexers](mailboxes/multiplexer.md)
+  - [Routers](mailboxes/routers.md)
+- [Actors](actors/index.md)
+  - [Actor](actors/actor.md)
+  - [Handler](actors/handler.md)
+  - [RemoteableActor](actors/remotable_actor.md)
+  - [Checkpointable](actors/checkpointable.md)
+  - [RemoteActor](actors/remote_actor.md)
+  - [Binds](actors/binds.md)
+  - [RemoteHandles](actors/remote_handles.md)
+  - [ActorHandle](actors/actor_handle.md)
+  - [Actor Lifecycle](actors/actor_lifecycle.md)
+- [Macros](macros/index.md)
+  - [`#[derive(Handler)]`](macros/handler.md)
+  - [`#[derive(HandleClient)]`](macros/handle_client.md)
+  - [`#[derive(RefClient)]`](macros/ref_client.md)
+  - [`#[derive(Named)]`](macros/named.md)
+  - [`#[export]`](macros/export.md)
+  - [`#[forward]`](macros/forward.md)