New sectiosn including doc link and explanation

README.md

@@ -19,29 +19,40 @@ These are more simplified versions of examples that exist in the [accelerate](ht
 
 ## How each example is made
 
-In the `code_examples` folder are basic text-like files which contain a much simplified version of some integration. For example:
+In the `code_examples` folder are basic text-like files which contain a much-simplified version of some integration. For example:
 
 ```
+##
 <pre>
-from accelerate import Accelerator
-accelerator = Accelerator()
-train_dataloader, model, optimizer scheduler = accelerator.prepare(
-        dataloader, model, optimizer, scheduler
-)
-
-model.train()
-for batch in train_dataloader:
-&nbsp;&nbsp;&nbsp;&nbsp;optimizer.zero_grad()
++from accelerate import Accelerator
++accelerator = Accelerator()
++dataloader, model, optimizer scheduler = accelerator.prepare(
++        dataloader, model, optimizer, scheduler
++)
+
+for batch in dataloader:
+    optimizer.zero_grad()
     inputs, targets = batch
+-    inputs = inputs.to(device)
+-    targets = targets.to(device)
     outputs = model(inputs)
     loss = loss_function(outputs, targets)
-    accelerator.backward(loss)
+-    loss.backward()
++    accelerator.backward(loss)
     optimizer.step()
-    scheduler.step()
-</pre>
+    scheduler.step()</pre>
+##
+Everything around `accelerate` ...
+
+##
+To learn more checkout the related documentation:
 ```
 
-These are done in an HTML-like syntax, with `pre` being used instead of three back-ticks for formatting purposes. 
+There are three overall "sections" separated by two "##" and a newline:
+
+1. The code diff that should be rendered with the new code
+2. An explanation of what the diff represents and what's new. Should be up to a paragraph as a TL;DR
+3. Link to the documentation users can go to quickly to learn more.
 
 ## Creating a `diff`
 

code_samples/basic

@@ -1,3 +1,4 @@
+##
 <pre>
 +from accelerate import Accelerator
 +accelerator = Accelerator()
@@ -15,4 +16,16 @@ for batch in dataloader:
 -    loss.backward()
 +    accelerator.backward(loss)
     optimizer.step()
-    scheduler.step()</pre>
+    scheduler.step()</pre>
+##
+Everything around `accelerate` occurs with the `Accelerator` class. To use it, first make an object.
+Then call `.prepare` passing in the PyTorch objects that you would normally train with. This will
+return the same objects, but they will be on the correct device and distributed if needed. Then
+you can train as normal, but instead of calling `loss.backward()` you call `accelerator.backward(loss)`.
+Also note that you don't need to call `model.to(device)` or `inputs.to(device)` anymore, as this
+is done automatically by `accelerator.prepare()`.
+
+##
+To learn more checkout the related documentation:
+- [Basic Tutorial](https://huggingface.co/docs/accelerate/basic_tutorials/migration)
+- [The Accelerator](https://huggingface.co/docs/accelerate/package_reference/accelerator)

src/app.py

@@ -1,10 +1,10 @@
 import gradio as gr
-from markup import highlight
+from markup import highlight, get_text
 from template import get_templates
 
 templates = get_templates()
 
-def change(inp):
+def change(inp, components=[]):
     """Based on an `inp`, render and highlight the appropriate code sample.
 
     Args:
@@ -14,12 +14,16 @@ def change(inp):
     Returns:
         `tuple`: A tuple of the initial code, the highlighted code, and the title for the section.
     """
+    code, explanation, docs = get_text(inp)
     if inp == "Basic":
-        return (templates["initial"], highlight(inp), "## Accelerate Code (Base Integration)")
+        return (templates["initial"], highlight(code), "## Accelerate Code (Base Integration)", explanation, docs)
     elif inp == "Calculating Metrics":
-        return (templates["initial_with_metrics"], highlight(inp), f"## Accelerate Code ({inp})")
+        return (templates["initial_with_metrics"], highlight(inp), f"## Accelerate Code ({inp})", explanation, docs)
     else:
-        return (templates["accelerate"], highlight(inp), f"## Accelerate Code ({inp})")
+        return (templates["accelerate"], highlight(inp), f"## Accelerate Code ({inp})", explanation, docs)
+
+initial_md = gr.Markdown("## Initial Code")
+initial_code = gr.Markdown(templates["initial"])
 
 with gr.Blocks() as demo:
     gr.Markdown(f'''# Accelerate Training Code Template Generator
@@ -31,10 +35,21 @@ Select how you would like to introduce an Accelerate capability to add to it.'''
     )
     with gr.Row():
         with gr.Column():
-            gr.Markdown("## Initial Code")
-            code = gr.Markdown(templates["initial"])
+            initial_md.render()
+            initial_code.render()
         with gr.Column():
             feature = gr.Markdown("## Accelerate Code")
             out = gr.Markdown()
-    inp.change(fn=change, inputs=inp, outputs=[code, out, feature])  
+    with gr.Row():
+        with gr.Column():    
+            gr.Markdown("## Documentation Links")
+            docs = gr.Markdown()
+        with gr.Column():    
+            gr.Markdown("## Explanation")
+            explanation = gr.Markdown()
+    inp.change(
+        fn=change, 
+        inputs=inp, 
+        outputs=[initial_code, out, feature, explanation, docs]
+    )
 demo.launch()

src/markup.py

@@ -35,17 +35,14 @@ def mark_text(text, add=True):
         color = _remove_color
     return f'<mark style="background-color:{color}!important;color:white!important">{text}</mark>'
 
-def highlight(option:str):
-    """Takes an option and returns the respective highlighted code sample.
+def highlight(code:str):
+    """Takes in code and returns the respective highlighted code sample.
 
     Args:
-        option (`str`):
-            A menu option chosen from the interface.
+        code (`str`):
+            Code from a file.
     """
-    filename = option.lower().replace(' ', '_')
-    with open(get_filename(filename)) as f:
-        output = f.read()
-    lines = output.split("\n")
+    lines = code.split("\n")
     for i,line in enumerate(lines):
         if line.startswith("-"):
             lines[i] = "- " + line[1:]
@@ -56,3 +53,13 @@ def highlight(option:str):
         else:
             lines[i] = "  " + line
     return "\n".join(lines).rstrip()
+
+def get_text(option):
+    """
+    Reads in an option and returns the code, explanation, and documentation links
+    """
+    filename = option.lower().replace(' ', '_')
+    with open(get_filename(filename)) as f:
+        output = f.read()
+    code, explanation, doclink = output.split("##\n")[1:]
+    return code, explanation, doclink