Make tutorials available on the site (#420)

Author: svekars

docs/Tutorials/ReadMe.MD

@@ -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
 )
@@ -82,8 +84,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 +175,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,14 +215,15 @@ 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",
     "promote_jupyter_magic": True,
     "backreferences_dir": None,
     "show_signature": False,
     "write_computation_times": False,
+    "ignore_pattern": r".*\.md$|.*\.MD$",  # Explicitly ignore markdown files
 }
 
 
@@ -222,5 +234,42 @@ 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)

docs/source/_static/logo-icon.svg

@@ -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"]
@@ -392,4 +394,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)

docs/source/conf.py

@@ -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!
 
@@ -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)

…Tutorials/1_RL_and_Forge_Fundamentals.MD …-to-forge/1_RL_and_Forge_Fundamentals.mddocs/Tutorials/1_RL_and_Forge_Fundamentals.MD renamed to docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.md docs/Tutorials/1_RL_and_Forge_Fundamentals.MD renamed to docs/source/tutorial_sources/zero-to-forge/1_RL_and_Forge_Fundamentals.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.
 

docs/Tutorials/2_Forge_Internals.MD …urces/zero-to-forge/2_Forge_Internals.mddocs/Tutorials/2_Forge_Internals.MD renamed to docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md docs/Tutorials/2_Forge_Internals.MD renamed to docs/source/tutorial_sources/zero-to-forge/2_Forge_Internals.md

@@ -6,4 +6,5 @@
 ```{toctree}
 :maxdepth: 1
 
+zero-to-forge-intro
 ```

docs/Tutorials/3_Monarch_101.MD …l_sources/zero-to-forge/3_Monarch_101.mddocs/Tutorials/3_Monarch_101.MD renamed to docs/source/tutorial_sources/zero-to-forge/3_Monarch_101.md docs/Tutorials/3_Monarch_101.MD renamed to docs/source/tutorial_sources/zero-to-forge/3_Monarch_101.md

@@ -0,0 +1,29 @@
+# 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](./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!
+
+## 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
+```