Skeleton for writing monarch presentation demo

Using a gallery file so it is easy to generate a webpage and notebook from it. added some option config to the sphinx build so that one demo can be quickly rebuild without redoing the whole docs.

Differential Revision: [D84272165](https://our.internmc.facebook.com/intern/diff/D84272165/)

**NOTE FOR REVIEWERS**: This PR has internal Meta-specific changes or comments, please review them on [Phabricator](https://our.internmc.facebook.com/intern/diff/D84272165/)!

ghstack-source-id: 315168912
Pull Request resolved: #1478

Author: zdevito

docs/source/_static/message_flow.svg

@@ -0,0 +1,18 @@
+import os
+
+from IPython.display import display, HTML
+
+
+def show_svg(filename: str) -> None:
+    """Display an SVG file centered in the notebook.
+
+    Args:
+        filename: Name of the SVG file (e.g., 'message_flow.svg')
+    """
+    cwd = os.getcwd()
+    monarch_path, subpath = cwd.rsplit("/docs", maxsplit=1)
+    svg_path = os.path.join(monarch_path, "source", "assets", filename)
+    with open(svg_path, "r") as f:
+        svg_content = f.read()
+    html_content = f'<div style="text-align: center;">{svg_content}</div>'
+    display(HTML(html_content))

docs/source/assets/__init__.py

@@ -63,6 +63,7 @@
 sys.path.insert(0, os.path.abspath("."))
 sys.path.insert(0, os.path.abspath("../.."))
 sys.path.insert(0, os.path.abspath("_ext"))  # Add our custom extensions
+sys.path.insert(0, os.path.abspath("generated/examples"))  # assets for examples
 
 html_theme = "pytorch_sphinx_theme2"
 html_theme_path = [pytorch_sphinx_theme2.get_html_theme_path()]
@@ -159,6 +160,16 @@
     ".md": "markdown",
 }
 
+
+ONE_GALLERY_EXAMPLE = os.environ.get("ONE_GALLERY_EXAMPLE", None)
+if ONE_GALLERY_EXAMPLE is not None:
+    import re
+
+    exclude_patterns = ["**"]  # Reset exclude_patterns to ensure books are included
+    sphinx_gallery_conf["filename_pattern"] = re.escape(ONE_GALLERY_EXAMPLE)
+    sphinx_gallery_conf["plot_gallery"] = "True"
+    sphinx_gallery_conf["only_warn_on_example_error"] = "False"
+
 # Configure MyST-Parser to properly handle relative links in the books directory
 myst_url_schemes = ["http", "https", "mailto"]
 

docs/source/assets/config.py

@@ -0,0 +1,55 @@
+# 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.
+
+# pyre-unsafe
+
+"""
+Getting Started
+===============
+
+This guide introduces the core concepts of Monarch, a framework for building
+multi-machine training programs using actors. We'll cover:
+
+- Defining actors with endpoint functions
+- Spawning actors locally and across multiple hosts and processes
+- Sending messages and organizing actors into meshes
+- The supervision tree for fault tolerance
+- Distributed tensors and RDMA capabilities
+"""
+
+from assets import show_svg
+
+# %%
+# Defining an Actor
+# -----------------
+# At its core, Monarch uses actors as a way to create multi-machine training programs.
+# Actors are Python objects that expose a number of endpoint functions. These functions
+# can be called by other actors in the system and their responses gathered asynchronously.
+#
+# Let's start by defining a simple actor:
+
+from monarch.actor import Actor, endpoint, this_proc
+
+
+class Counter(Actor):
+    def __init__(self, initial_value: int):
+        self.value = initial_value
+
+    @endpoint
+    def increment(self) -> None:
+        self.value += 1
+
+    @endpoint
+    def get_value(self) -> int:
+        return self.value
+
+
+# %%
+# Message Flow Diagram
+# ===================
+# Here's how messages flow between actors:
+
+show_svg("message_flow.svg")