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/_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 4e3cec1fa..2ee6771ea 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 ) @@ -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,7 +215,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 +223,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 +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) 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 99% 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 index 39b6d62aa..42f234772 100644 --- a/docs/Tutorials/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"] @@ -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) 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..13e59da48 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! @@ -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) 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..45a352bbe --- /dev/null +++ b/docs/source/zero-to-forge-intro.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 +```