Add examples component to docs (#1729)

* Add examples to docs

* Adding guide for examples

* Exclude guides from methods

* PR feedback: typos, different allowed values of examples, docstrings

demo/calculator_blocks/run.py

@@ -0,0 +1,33 @@
+import gradio as gr
+
+
+def calculator(num1, operation, num2):
+    if operation == "add":
+        return num1 + num2
+    elif operation == "subtract":
+        return num1 - num2
+    elif operation == "multiply":
+        return num1 * num2
+    elif operation == "divide":
+        return num1 / num2
+
+
+with gr.Blocks() as demo:
+    with gr.Row():
+        with gr.Column():
+            num_1 = gr.Number()
+            operation = gr.Radio(["add", "subtract", "multiply", "divide"])
+            num_2 = gr.Number()
+            submit_btn = gr.Button(value="Calculate")
+        with gr.Column():
+            result = gr.Number()
+
+    submit_btn.click(calculator, inputs=[num_1, operation, num_2], outputs=[result])
+    examples = gr.Examples(examples=[[5, "add", 3],
+                                     [4, "divide", 2],
+                                     [-4, "multiply", 2.5],
+                                     [0, "subtract", 1.2]],
+                           inputs=[num_1, operation, num_2])
+
+if __name__ == "__main__":
+    demo.launch()

demo/calculator_blocks_cached/run.py

@@ -0,0 +1,36 @@
+import gradio as gr
+
+
+def calculator(num1, operation, num2):
+    if operation == "add":
+        return num1 + num2
+    elif operation == "subtract":
+        return num1 - num2
+    elif operation == "multiply":
+        return num1 * num2
+    elif operation == "divide":
+        return num1 / num2
+
+
+with gr.Blocks() as demo:
+    with gr.Row():
+        with gr.Column():
+            num_1 = gr.Number()
+            operation = gr.Radio(["add", "subtract", "multiply", "divide"])
+            num_2 = gr.Number()
+            submit_btn = gr.Button(value="Calculate")
+        with gr.Column():
+            result = gr.Number()
+
+    submit_btn.click(calculator, inputs=[num_1, operation, num_2], outputs=[result])
+    examples = gr.Examples(examples=[[5, "add", 3],
+                                     [4, "divide", 2],
+                                     [-4, "multiply", 2.5],
+                                     [0, "subtract", 1.2]],
+                           inputs=[num_1, operation, num_2],
+                           outputs=[result],
+                           fn=calculator,
+                           cache_examples=True)
+
+if __name__ == "__main__":
+    demo.launch()

gradio/examples.py

@@ -9,6 +9,7 @@ import shutil
 from typing import TYPE_CHECKING, Any, Callable, List, Optional, Tuple
 
 from gradio.components import Dataset
+from gradio.documentation import document, set_documentation_group
 from gradio.flagging import CSVLogger
 
 if TYPE_CHECKING:  # Only import for type checking (to avoid circular imports).
@@ -17,8 +18,20 @@ if TYPE_CHECKING:  # Only import for type checking (to avoid circular imports).
 
 CACHED_FOLDER = "gradio_cached_examples"
 
+set_documentation_group("component-helpers")
 
+
+@document("cache_interface_examples", "load_from_cache", "process_example")
 class Examples:
+    """
+    This class is a wrapper over the Dataset component and can be used to create Examples
+    for Blocks / Interfaces. Populates the Dataset component with examples and
+    assigns event listener so that clicking on an example populates the input/output
+    components. Optionally handles example caching for fast inference.
+
+    Demos: blocks_inputs, fake_gan
+    """
+
     def __init__(
         self,
         examples: List[Any] | List[List[Any]] | str,
@@ -29,18 +42,13 @@ class Examples:
         examples_per_page: int = 10,
     ):
         """
-        This class is a wrapper over the Dataset component can be used to create Examples
-        for Blocks / Interfaces. Populates the Dataset component with examples and
-        assigns event listener so that clicking on an example populates the input/output
-        components. Optionally handles example caching for fast inference.
-
         Parameters:
-        examples (List[Any] | List[List[Any]] | str): example inputs that can be clicked to populate specific components. Should be nested list, in which the outer list consists of samples and each inner list consists of an input corresponding to each input component. A string path to a directory of examples can also be provided.
-        inputs: (Component | List[Component]): the component or list of components corresponding to the examples
-        outputs: (Component | List[Component] | None): optionally, provide the component or list of components corresponding to the output of the examples. Required if `cache` is True.
-        fn: (Callable | None): optionally, provide the function to run to generate the outputs corresponding to the examples. Required if `cache` is True.
-        cache_examples (bool): if True, caches examples for fast runtime. If True, then `fn` and `outputs` need to be provided
-        examples_per_page (int): how many examples to show per page (this parameter currently has no effect)
+            examples: example inputs that can be clicked to populate specific components. Should be nested list, in which the outer list consists of samples and each inner list consists of an input corresponding to each input component. A string path to a directory of examples can also be provided.
+            inputs: the component or list of components corresponding to the examples
+            outputs: optionally, provide the component or list of components corresponding to the output of the examples. Required if `cache` is True.
+            fn: optionally, provide the function to run to generate the outputs corresponding to the examples. Required if `cache` is True.
+            cache_examples: if True, caches examples for fast runtime. If True, then `fn` and `outputs` need to be provided
+            examples_per_page: how many examples to show per page (this parameter currently has no effect)
         """
         if cache_examples and (fn is None or outputs is None):
             raise ValueError("If caching examples, `fn` and `outputs` must be provided")
@@ -180,7 +188,10 @@ class Examples:
                     raise e
 
     def process_example(self, example_id: int) -> Tuple[List[Any], List[float]]:
-        """Loads an example from the interface and returns its prediction."""
+        """Loads an example from the interface and returns its prediction.
+        Parameters:
+            example_id: The id of the example to process (zero-indexed).
+        """
         example_set = self.examples[example_id]
         raw_input = [
             self.inputs[i].preprocess_example(example)
@@ -203,7 +214,10 @@ class Examples:
         return processed_output
 
     def load_from_cache(self, example_id: int) -> List[Any]:
-        """Loads a particular cached example for the interface."""
+        """Loads a particular cached example for the interface.
+        Parameters:
+            example_id: The id of the example to process (zero-indexed).
+        """
         with open(self.cached_file) as cache:
             examples = list(csv.reader(cache, quotechar="'"))
         example = examples[example_id + 1]  # +1 to adjust for header

gradio/layouts.py

@@ -165,8 +165,8 @@ class TabItem(BlockContext):
     def __init__(self, label: str, id: Optional[int | str] = None, **kwargs):
         """
         Parameters:
-        label (str): The visual label for the tab
-        id: (Optional[int | str]): An optional identifier for the tab, required if you wish to control the selected tab from a predict function.
+            label: The visual label for the tab
+            id: An optional identifier for the tab, required if you wish to control the selected tab from a predict function.
         """
         super().__init__(**kwargs)
         self.label = label

guides/adding_examples_to_your_app.md

@@ -0,0 +1,91 @@
+# Adding Examples To Your App
+
+Docs: examples
+
+## Introduction
+
+As we saw in the [Quickstart](/getting_started#example-inputs), providing example inputs to your app are a helpful way
+to let your audience explore the functionality of your app without having them specify all of your app's expected inputs.
+
+In this guide we'll go into greater depth on how you can provide example inputs to your apps.
+
+## Adding examples to an Interface
+
+As covered in the Quickstart, adding examples to an Interface is as easy as providing a list of lists to the `examples`
+keyword argument. 
+Each sublist is a data sample, where each element corresponds to an input of the prediction function.
+The inputs must be ordered in the same order as the prediction function expects them.
+
+We can see the `examples` parameter in action in this calculator demo:
+
+$code_calculator
+$demo_calculator
+
+If your interface only has one input component, then you can provide your examples as a regular list instead of a list of lists.
+
+You can also specify a path to a directory containing your examples. In the case of multiple inputs, this directory must
+contain a log.csv file with the example values.
+In the context of the calculator demo, we can change `examples` to be `examples=/demo/calculator/examples` and in that directory we include the following `log.csv` file:
+```csv
+num,operation,num2
+5,"add",3
+4,"divide",2
+5,"multiply",3
+```
+
+
+## Adding examples to a Blocks app
+
+In order to add examples to an app written with the Blocks API, you need to use the `gr.Examples` component helper.
+This class is a wrapper over the `gr.Dataset` component.
+
+During class creation, `gr.Examples` will instantiate a `gr.Dataset` and attach an event listener on the dataset click event
+that will populate all the inputs with the values of that row of the dataset. 
+
+To show this in practice, we will build the same calculator but with Blocks instead of an Interface.
+
+$code_calculator_blocks
+$demo_calculator_blocks
+
+By the way, Interface uses `gr.Examples` under the hood too!
+So if you know how this example works you also know how the Interface examples work! 🥳
+
+## Caching examples
+
+Both `gr.Examples` and `Interface` have a `cache_examples` parameter.
+The default in the previous demos is to not cache examples, but if `cache_examples=True`, the `gr.Examples` component will
+run all of your examples through your app and save the outputs when you call the `launch()` method.
+Whenever someone clicks on an example, the output will automatically be populated in the app.
+This is useful especially when your model can take a while to run!  
+
+We can see this in the following demo.
+It's the same as the previous calculator with only the changes needed to cache examples.
+
+$code_calculator_blocks_cached
+$demo_calculator_blocks_cached
+
+Note that when using `gr.Examples` and with `cache_examples=True`, you must specify the output component and the function
+to run.
+
+## Providing examples for only a subset of inputs
+
+Sometimes your app has many possible inputs, but you would only like to provide examples for a subset of them.
+
+For example, consider an app showcasing an image classification algorithm.
+The app inputs are a sample image to classify with some additional sliders to control the algorithm. 
+In this case, you may want to only provide examples for the image and let your users control the sliders themselves.
+
+In order to exclude some inputs from the examples, pass `None` for all data samples corresponding to that particular input.
+
+In the following example, we have an app demoing a GAN. Note how the last three examples do not show up in the examples
+dataset.
+
+$code_fake_gan
+$demo_fake_gan
+
+## Next Steps
+
+Now that you know all about adding examples to your apps, here are some good next steps:
+
+* Check out [the free Gradio course](https://huggingface.co/course/chapter9/1) for a step-by-step walkthrough of everything Gradio-related with lots of examples of how to build your own machine learning demos 📖
+* If you just want to explore what demos other people have built with Gradio, [browse public Hugging Face Spaces](http://hf.space/), view the underlying Python code, and be inspired 🤗

guides/create_your_own_friends_with_a_gan.md

@@ -2,7 +2,7 @@
 
 Related spaces: https://huggingface.co/spaces/NimaBoscarino/cryptopunks, https://huggingface.co/spaces/nateraw/cryptopunks-generator
 Tags: GAN, IMAGE, HUB
-Docs: slider, image
+Docs: slider, image, examples
 
 Contributed by <a href="https://huggingface.co/NimaBoscarino">Nima Boscarino</a> and <a href="https://huggingface.co/nateraw">Nate Raw</a>
 

guides/getting_started.md

@@ -1,6 +1,7 @@
 # Quickstart
 
 Pinned: 0
+Docs: examples
 
 **Prerequisite**: Gradio requires Python 3.7 or above, that's it! 
 

guides/image_classification_in_pytorch.md

@@ -2,7 +2,7 @@
 
 Related spaces: https://huggingface.co/spaces/abidlabs/pytorch-image-classifier, https://huggingface.co/spaces/pytorch/ResNet, https://huggingface.co/spaces/pytorch/ResNext, https://huggingface.co/spaces/pytorch/SqueezeNet
 Tags: VISION, RESNET, PYTORCH
-Docs: image, label
+Docs: image, label, example
 
 ## Introduction
 

guides/image_classification_in_tensorflow.md

@@ -2,7 +2,7 @@
 
 Related spaces: https://huggingface.co/spaces/abidlabs/keras-image-classifier
 Tags: VISION, MOBILENET, TENSORFLOW
-Docs: image, label
+Docs: image, label, examples
 
 ## Introduction
 

guides/image_classification_with_vision_transformers.md

@@ -2,7 +2,7 @@
 
 Related spaces: https://huggingface.co/spaces/abidlabs/vision-transformer
 Tags: VISION, TRANSFORMERS, HUB
-Docs: image, label
+Docs: image, label, examples
 
 ## Introduction
 

guides/using_hugging_face_integrations.md

@@ -2,6 +2,7 @@
 
 Related spaces: https://huggingface.co/spaces/farukozderim/Model-Comparator-Space-Builder, https://huggingface.co/spaces/osanseviero/helsinki_translation_en_es, https://huggingface.co/spaces/osanseviero/remove-bg-webcam, https://huggingface.co/spaces/mrm8488/GPT-J-6B, https://huggingface.co/spaces/akhaliq/T0pp, https://huggingface.co/spaces/osanseviero/mix_match_gradio
 Tags: HUB, SPACES, EMBED
+Docs: examples
 
 Contributed by <a href="https://huggingface.co/osanseviero">Omar Sanseviero</a> 🦙 and <a href="https://huggingface.co/farukozderim">Ömer Faruk Özdemir</a>
 

website/homepage/src/docs/__init__.py

@@ -61,8 +61,9 @@ def add_supported_events():
 add_supported_events()
 
 def add_guides():
-    for component in docs["component"]:
-        component["guides"] = [guide for guide in guides if component["name"].lower() in guide["docs"]]
+    for mode in docs:
+        for obj in docs[mode]:
+            obj["guides"] = [guide for guide in guides if obj["name"].lower() in guide["docs"]]
 
 add_guides()
 

website/homepage/src/docs/obj_doc_template.html

@@ -113,14 +113,14 @@
     <h4 class="mt-4 p-3 font-semibold">Methods</h4>
       <div class="flex flex-col gap-8 pl-12">
         {% for fn in obj["fns"] %}
-          {% with obj=fn, parent=parent + "." + obj["name"] %}
+          {% with obj=fn, is_class=False, parent=parent + "." + obj["name"] %}
             {% include "docs/obj_doc_template.html" %}
           {% endwith %}
         {% endfor %}
       <div class="ml-12">
     </div>
   {% endif %}
-  {% if is_component %}
+  {% if is_class %}
    <h4 class="my-2 font-semibold">Step-by-step Guides</h4>
       {% if obj["guides"] %}
         <div class="guides-list grid grid-cols-1 lg:grid-cols-4 gap-4">

website/homepage/src/docs/template.html

@@ -21,6 +21,10 @@
         {% for component in docs["component"] %}
           <a class="px-4 block thin-link" href="#{{ component['name'].lower() }}">{{ component['name'] }}</a>
         {% endfor %}
+        <a class="link px-4 my-2 block" href="#component-helpers">Component Helpers
+        {% for component in docs["component-helpers"] %}
+          <a class="px-4 block thin-link" href="#{{ component['name'].lower() }}">{{ component['name'] }}</a>
+        {% endfor %}
       </div>
       <div class="flex flex-col">
         <p class="bg-gradient-to-r from-orange-100 to-orange-50 border border-orange-200 px-4 py-1 rounded-full text-orange-800 mb-1">
@@ -91,7 +95,22 @@
             <img src="/assets/img/dataflow.svg" class="mt-4">
           </div>
           {% for component in docs["component"] %}
-            {% with obj=component, is_component=True, parent="gradio" %}
+            {% with obj=component, is_class=True, parent="gradio" %}
+              {% include "docs/obj_doc_template.html" %}
+            {% endwith %}
+          {% endfor %}
+        </section>
+        <section id="component-helpers" class="pt-2 flex flex-col gap-10">
+          <div>
+            <h2 id="component-helpers-header"
+                class="text-4xl font-light mb-2 pt-2 text-orange-500">Components Helpers</h2>
+            <p class="mt-8 text-lg">
+              Gradio includes helper classes that abstract over existing components. The goal of these classes is to help you
+              add common functionality to your app without having to repeatedly create the same components and event listeners.
+            </p>
+          </div>
+          {% for component in docs["component-helpers"] %}
+            {% with obj=component, is_class=True, parent="gradio" %}
               {% include "docs/obj_doc_template.html" %}
             {% endwith %}
           {% endfor %}