From 3d0ca51ce3a235623caff2e4ce85fe39e0a387f7 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 09:02:54 -0700 Subject: [PATCH 1/9] Make tutorials available on the site --- docs/Tutorials/ReadMe.MD | 19 ------- docs/source/conf.py | 49 ++++++++++++++++++- .../1_RL_and_Forge_Fundamentals.md} | 0 .../zero-to-forge/2_Forge_Internals.md} | 2 +- .../zero-to-forge/3_Monarch_101.md} | 2 +- docs/source/tutorials.md | 1 + docs/source/zero-to-forge-intro.md | 27 ++++++++++ 7 files changed, 77 insertions(+), 23 deletions(-) delete mode 100644 docs/Tutorials/ReadMe.MD rename docs/{Tutorials/1_RL_and_Forge_Fundamentals.MD => source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md} (100%) rename docs/{Tutorials/2_Forge_Internals.MD => source/tutorial_sources/zero-to-forge/2_Forge_Internals.md} (99%) rename docs/{Tutorials/3_Monarch_101.MD => source/tutorial_sources/zero-to-forge/3_Monarch_101.md} (99%) create mode 100644 docs/source/zero-to-forge-intro.md diff --git a/docs/Tutorials/ReadMe.MD b/docs/Tutorials/ReadMe.MD deleted file mode 100644 index 084710853..000000000 --- a/docs/Tutorials/ReadMe.MD +++ /dev/null @@ -1,19 +0,0 @@ -## Zero to Forge: From RL Theory to Production-Scale Implementation - -A comprehensive guide for ML Engineers building distributed RL systems for language models. - -Some of the examples mentioned below will be conceptual in nature for understanding. Please refer to API Docs (Coming Soon!) for more details - -Welcome to the Tutorials section! This section is inspired by the A-Z PyTorch tutorial, shoutout to our PyTorch friends that remember! - -### - -This section currently is structured in 3 detailed parts: - -1. [RL Fundamentals and Understanding Forge Terminology](./1_RL_and_Forge_Fundamentals.MD): This gives a quick refresher of Reinforcement Learning and teaches you Forge Fundamentals -2. [Forge Internals](./2_Forge_Internals.MD): Goes a layer deeper and explains the internals of Forge -3. [Monarch 101](./3_Monarch_101.MD): It's a 101 to Monarch and how Forge Talks to Monarch - -Each part builds upon the next and the entire section can be consumed in roughly an hour-Grab a Chai and Enjoy! - -If you're eager, please checkout our SFT Tutorial too (Coming soon!) as well as [App Examples](../../apps/). diff --git a/docs/source/conf.py b/docs/source/conf.py index 4e3cec1fa..87db5e0df 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -82,8 +82,14 @@ def get_version_path(): "_templates", os.path.join(os.path.dirname(pytorch_sphinx_theme2.__file__), "templates"), ] -exclude_patterns = ["tutorials/index.rst", "tutorials/template_tutorial.rst"] +exclude_patterns = [ + "tutorials/index.rst", + "tutorials/template_tutorial.rst", + "tutorials/**/index.rst", + "tutorial_sources/**/*.md", # Exclude all markdown files from tutorial_sources + "tutorial_sources/**/*.MD", # Also exclude uppercase .MD files +] html_static_path = ["_static"] html_css_files = ["custom.css"] html_js_files = ["custom.js"] @@ -167,6 +173,9 @@ def get_version_path(): "html_image", ] +# Configure MyST parser to treat mermaid code blocks as mermaid directives +myst_fence_as_directive = ["mermaid"] + autodoc_default_options = { "members": True, "undoc-members": True, @@ -204,7 +213,7 @@ def get_version_path(): sphinx_gallery_conf = { "examples_dirs": "tutorial_sources", # Path to examples directory "gallery_dirs": "tutorials", # Path to generate gallery - "filename_pattern": ".*", # Include all files + "filename_pattern": r".*\.py$", # Only process .py files, not .md files "download_all_examples": False, "first_notebook_cell": "%matplotlib inline", "plot_gallery": "True", @@ -212,6 +221,7 @@ def get_version_path(): "backreferences_dir": None, "show_signature": False, "write_computation_times": False, + "ignore_pattern": r".*\.md$|.*\.MD$", # Explicitly ignore markdown files } @@ -222,5 +232,40 @@ def clean_docstring_indentation(app, what, name, obj, options, lines): lines.append("") +def copy_markdown_tutorials(app): + """Copy markdown files from tutorial_sources to tutorials directory. + + This runs after the builder is initialized but before sphinx-gallery processes files, + ensuring markdown files are available alongside generated .py tutorials. + """ + import shutil + from pathlib import Path + + source_dir = Path(app.srcdir) / "tutorial_sources" + target_dir = Path(app.srcdir) / "tutorials" + + # Ensure target directory exists + target_dir.mkdir(parents=True, exist_ok=True) + + # Walk through tutorial_sources and copy all .md files + for md_file in source_dir.rglob("*.md"): + # Skip README files + if md_file.name.lower() in ["readme.md", "readme.txt"]: + continue + + # Calculate relative path from tutorial_sources + rel_path = md_file.relative_to(source_dir) + + # Create target path in tutorials directory + target_path = target_dir / rel_path + target_path.parent.mkdir(parents=True, exist_ok=True) + + # Copy the file + shutil.copy2(md_file, target_path) + print(f"[Forge Docs] Copied {md_file.name} to {target_path.relative_to(app.srcdir)}") + + def setup(app): app.connect("autodoc-process-docstring", clean_docstring_indentation) + # Use builder-inited to ensure it runs before source files are read + app.connect("builder-inited", copy_markdown_tutorials) diff --git a/docs/Tutorials/1_RL_and_Forge_Fundamentals.MD b/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md similarity index 100% rename from docs/Tutorials/1_RL_and_Forge_Fundamentals.MD rename to docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md diff --git a/docs/Tutorials/2_Forge_Internals.MD b/docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md similarity index 99% rename from docs/Tutorials/2_Forge_Internals.MD rename to docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md index 1a9421a96..3f5e4b8a7 100644 --- a/docs/Tutorials/2_Forge_Internals.MD +++ b/docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md @@ -1,6 +1,6 @@ # Part 2: Peeling Back the Abstraction - What Are Services? -We highly recommend reading [Part 1](./1_RL_and_Forge_Fundamentals.MD) before this, it explains RL Concepts and how they land in Forge. +We highly recommend reading [Part 1](./1_RL_and_Forge_Fundamentals) before this, it explains RL Concepts and how they land in Forge. Now that you see the power of the service abstraction, let's understand what's actually happening under the hood, Grab your chai! diff --git a/docs/Tutorials/3_Monarch_101.MD b/docs/source/tutorial_sources/zero-to-forge/3_Monarch_101.md similarity index 99% rename from docs/Tutorials/3_Monarch_101.MD rename to docs/source/tutorial_sources/zero-to-forge/3_Monarch_101.md index 2213e9bb5..faf21e159 100644 --- a/docs/Tutorials/3_Monarch_101.MD +++ b/docs/source/tutorial_sources/zero-to-forge/3_Monarch_101.md @@ -1,6 +1,6 @@ # Part 3: The Forge-Monarch Connection -This is part 3 of our series, in the previous sections: we learned Part 1: [RL Concepts and how they map to Forge](./1_RL_and_Forge_Fundamentals.MD), Part 2: [Forge Internals](./2_Forge_Internals.MD). +This is part 3 of our series, in the previous sections: we learned Part 1: [RL Concepts and how they map to Forge](./1_RL_and_Forge_Fundamentals), Part 2: [Forge Internals](./2_Forge_Internals). Now let's peel back the layers. Forge services are built on top of **Monarch**, PyTorch's distributed actor framework. Understanding this connection is crucial for optimization and debugging. diff --git a/docs/source/tutorials.md b/docs/source/tutorials.md index 6e06c636a..ad56f3a59 100644 --- a/docs/source/tutorials.md +++ b/docs/source/tutorials.md @@ -6,4 +6,5 @@ ```{toctree} :maxdepth: 1 +zero-to-forge-intro ``` diff --git a/docs/source/zero-to-forge-intro.md b/docs/source/zero-to-forge-intro.md new file mode 100644 index 000000000..65b321a39 --- /dev/null +++ b/docs/source/zero-to-forge-intro.md @@ -0,0 +1,27 @@ +# Zero to Forge: From RL Theory to Production-Scale Implementation + +A comprehensive guide for ML Engineers building distributed RL systems for language models. + +Some of the examples mentioned below will be conceptual in nature for understanding. Please refer to API Docs (Coming Soon!) for more details + +Welcome to the Tutorials section! This section is inspired by the A-Z PyTorch tutorial, shoutout to our PyTorch friends that remember! + +## Tutorial Structure + +This section currently is structured in 3 detailed parts: + +1. [RL Fundamentals and Understanding Forge Terminology](tutorials/zero-to-forge/1_RL_and_Forge_Fundamentals): This gives a quick refresher of Reinforcement Learning and teaches you Forge Fundamentals +2. [Forge Internals](tutorials/zero-to-forge/2_Forge_Internals): Goes a layer deeper and explains the internals of Forge +3. [Monarch 101](tutorials/zero-to-forge/3_Monarch_101): It's a 101 to Monarch and how Forge Talks to Monarch + +Each part builds upon the next and the entire section can be consumed in roughly an hour - Grab a Chai and Enjoy! + +If you're eager, please checkout our SFT Tutorial too (Coming soon!)! + +```{toctree} +:maxdepth: 1 +:hidden: +tutorials/zero-to-forge/1_RL_and_Forge_Fundamentals +tutorials/zero-to-forge/2_Forge_Internals +tutorials/zero-to-forge/3_Monarch_101 +``` From f4c5d0160a9f2dbbd3c7ba330fdb159a4d7005ac Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 09:07:17 -0700 Subject: [PATCH 2/9] Precommit --- docs/source/conf.py | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 87db5e0df..f0898a09d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -234,35 +234,37 @@ def clean_docstring_indentation(app, what, name, obj, options, lines): def copy_markdown_tutorials(app): """Copy markdown files from tutorial_sources to tutorials directory. - + This runs after the builder is initialized but before sphinx-gallery processes files, ensuring markdown files are available alongside generated .py tutorials. """ import shutil from pathlib import Path - + source_dir = Path(app.srcdir) / "tutorial_sources" target_dir = Path(app.srcdir) / "tutorials" - + # Ensure target directory exists target_dir.mkdir(parents=True, exist_ok=True) - + # Walk through tutorial_sources and copy all .md files for md_file in source_dir.rglob("*.md"): # Skip README files if md_file.name.lower() in ["readme.md", "readme.txt"]: continue - + # Calculate relative path from tutorial_sources rel_path = md_file.relative_to(source_dir) - + # Create target path in tutorials directory target_path = target_dir / rel_path target_path.parent.mkdir(parents=True, exist_ok=True) - + # Copy the file shutil.copy2(md_file, target_path) - print(f"[Forge Docs] Copied {md_file.name} to {target_path.relative_to(app.srcdir)}") + print( + f"[Forge Docs] Copied {md_file.name} to {target_path.relative_to(app.srcdir)}" + ) def setup(app): From 8a1d5a22e850a0e8ad91e4e31909e69d0de9c463 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 09:21:38 -0700 Subject: [PATCH 3/9] Update --- .../zero-to-forge/1_RL_and_Forge_Fundamentals.md | 2 +- docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md b/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md index 39b6d62aa..db0ad9804 100644 --- a/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md +++ b/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md @@ -392,4 +392,4 @@ score = await reward_actor.evaluate_response.route( This is fundamentally different from monolithic RL implementations where any component failure stops everything! -In the next Section, we will go a layer deeper and learn how ForgeServices work. Continue to [Part 2 here](./2_Forge_Internals.MD) +In the next Section, we will go a layer deeper and learn how ForgeServices work. Continue to [Part 2 here](./2_Forge_Internals.md) diff --git a/docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md b/docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md index 3f5e4b8a7..13e59da48 100644 --- a/docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md +++ b/docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md @@ -668,4 +668,4 @@ print("All services shut down successfully!") This is the power of the service abstraction - complex distributed coordination looks like simple async Python code. -In the next part we will learn about [Monarch internals](./3_Monarch_101.MD) +In the next part we will learn about [Monarch internals](./3_Monarch_101.md) From ce81646278bd93831e654c47c5838cc56cb4ee96 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 09:53:57 -0700 Subject: [PATCH 4/9] Add favicon --- docs/source/_static/logo-icon.svg | 12 ++++++++++++ docs/source/conf.py | 2 ++ 2 files changed, 14 insertions(+) create mode 100644 docs/source/_static/logo-icon.svg diff --git a/docs/source/_static/logo-icon.svg b/docs/source/_static/logo-icon.svg new file mode 100644 index 000000000..9dcafc39a --- /dev/null +++ b/docs/source/_static/logo-icon.svg @@ -0,0 +1,12 @@ + + + + + + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py index f0898a09d..956979d81 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -65,6 +65,8 @@ def get_version_path(): "sphinx_gallery.gen_gallery", ] +html_favicon = "_static/logo-icon.svg" + html_baseurl = ( f"https://meta-pytorch.org/forge/{version_path}" # needed for sphinx-sitemap ) From 41ba210e8e84ed0a9b846cc4c8a48e42087db681 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 09:56:28 -0700 Subject: [PATCH 5/9] Precommit --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 956979d81..2ee6771ea 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -65,7 +65,7 @@ def get_version_path(): "sphinx_gallery.gen_gallery", ] -html_favicon = "_static/logo-icon.svg" +html_favicon = "_static/logo-icon.svg" html_baseurl = ( f"https://meta-pytorch.org/forge/{version_path}" # needed for sphinx-sitemap From 2d5906e6fac3efa4befa6725d20928a4f68cce58 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 10:33:32 -0700 Subject: [PATCH 6/9] Fix diagram --- .../zero-to-forge/1_RL_and_Forge_Fundamentals.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md b/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md index db0ad9804..42f234772 100644 --- a/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md +++ b/docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md @@ -76,6 +76,7 @@ Here's the key insight: **Each RL component becomes a Forge service**. The toy e ```mermaid graph LR subgraph Concepts["RL Concepts"] + direction TB C1["Dataset"] C2["Policy"] C3["Reward Model"] @@ -85,6 +86,7 @@ graph LR end subgraph Services["Forge Services (Real Classes)"] + direction TB S1["DatasetActor"] S2["Policy"] S3["RewardActor"] From 41efc881843526770e66e6d4cd20aa8c7ec93f4a Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 11:59:19 -0700 Subject: [PATCH 7/9] Update --- docs/source/zero-to-forge-intro.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/zero-to-forge-intro.md b/docs/source/zero-to-forge-intro.md index 65b321a39..072cbbfb9 100644 --- a/docs/source/zero-to-forge-intro.md +++ b/docs/source/zero-to-forge-intro.md @@ -2,9 +2,11 @@ A comprehensive guide for ML Engineers building distributed RL systems for language models. -Some of the examples mentioned below will be conceptual in nature for understanding. Please refer to API Docs (Coming Soon!) for more details +Some of the examples mentioned below will be conceptual in nature for understanding. +Please refer to [API Docs](./api.html) for more details. -Welcome to the Tutorials section! This section is inspired by the A-Z PyTorch tutorial, shoutout to our PyTorch friends that remember! +Welcome to the Tutorials section! This section is inspired by the A-Z +PyTorch tutorial, shoutout to our PyTorch friends that remember! ## Tutorial Structure From 62fe77ace3108a0eca19915441d2573067d9f1e4 Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 12:35:46 -0700 Subject: [PATCH 8/9] Update --- docs/source/zero-to-forge-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/zero-to-forge-intro.md b/docs/source/zero-to-forge-intro.md index 072cbbfb9..a14110ec9 100644 --- a/docs/source/zero-to-forge-intro.md +++ b/docs/source/zero-to-forge-intro.md @@ -3,7 +3,7 @@ A comprehensive guide for ML Engineers building distributed RL systems for language models. Some of the examples mentioned below will be conceptual in nature for understanding. -Please refer to [API Docs](./api.html) for more details. +Please refer to [API Docs](./api) for more details. Welcome to the Tutorials section! This section is inspired by the A-Z PyTorch tutorial, shoutout to our PyTorch friends that remember! From dbc6f92b2f9590f20bea182ec87579ea65cd897d Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Wed, 15 Oct 2025 12:39:41 -0700 Subject: [PATCH 9/9] Precommit --- docs/source/zero-to-forge-intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/zero-to-forge-intro.md b/docs/source/zero-to-forge-intro.md index a14110ec9..45a352bbe 100644 --- a/docs/source/zero-to-forge-intro.md +++ b/docs/source/zero-to-forge-intro.md @@ -5,7 +5,7 @@ A comprehensive guide for ML Engineers building distributed RL systems for langu Some of the examples mentioned below will be conceptual in nature for understanding. Please refer to [API Docs](./api) for more details. -Welcome to the Tutorials section! This section is inspired by the A-Z +Welcome to the Tutorials section! This section is inspired by the A-Z PyTorch tutorial, shoutout to our PyTorch friends that remember! ## Tutorial Structure