Adding flagging callbacks to the docs (#1834)

* added flagging documentation

* formatting

* added example usage

* formatting

* addressed comments

gradio/flagging.py

@@ -10,10 +10,13 @@ from typing import TYPE_CHECKING, Any, List, Optional
 
 import gradio as gr
 from gradio import encryptor, utils
+from gradio.documentation import document, set_documentation_group
 
 if TYPE_CHECKING:
     from gradio.components import Component
 
+set_documentation_group("flagging")
+
 
 class FlaggingCallback(ABC):
     """
@@ -54,12 +57,23 @@ class FlaggingCallback(ABC):
         pass
 
 
+@document()
 class SimpleCSVLogger(FlaggingCallback):
     """
-    A simple example implementation of the FlaggingCallback abstract class
-    provided for illustrative purposes.
+    A simplified implementation of the FlaggingCallback abstract class
+    provided for illustrative purposes.  Each flagged sample (both the input and output data)
+    is logged to a CSV file on the machine running the gradio app.
+    Example:
+        import gradio as gr
+        def image_classifier(inp):
+            return {'cat': 0.3, 'dog': 0.7}
+        demo = gr.Interface(fn=image_classifier, inputs="image", outputs="label",
+                            flagging_callback=SimpleCSVLogger())
     """
 
+    def __init__(self):
+        pass
+
     def setup(self, components: List[Component], flagging_dir: str):
         self.components = components
         self.flagging_dir = flagging_dir
@@ -95,12 +109,22 @@ class SimpleCSVLogger(FlaggingCallback):
         return line_count
 
 
+@document()
 class CSVLogger(FlaggingCallback):
     """
-    The default implementation of the FlaggingCallback abstract class.
-    Logs the input and output data to a CSV file. Supports encryption.
+    The default implementation of the FlaggingCallback abstract class. Each flagged
+    sample (both the input and output data) is logged to a CSV file with headers on the machine running the gradio app.
+    Example:
+        import gradio as gr
+        def image_classifier(inp):
+            return {'cat': 0.3, 'dog': 0.7}
+        demo = gr.Interface(fn=image_classifier, inputs="image", outputs="label",
+                            flagging_callback=CSVLogger())
     """
 
+    def __init__(self):
+        pass
+
     def setup(
         self,
         components: List[Component],
@@ -203,37 +227,38 @@ class CSVLogger(FlaggingCallback):
         return line_count
 
 
+@document()
 class HuggingFaceDatasetSaver(FlaggingCallback):
     """
-    A FlaggingCallback that saves flagged data to a HuggingFace dataset.
+    A callback that saves each flagged sample (both the input and output data)
+    to a HuggingFace dataset.
+    Example:
+        import gradio as gr
+        hf_writer = gr.HuggingFaceDatasetSaver(HF_API_TOKEN, "image-classification-mistakes")
+        def image_classifier(inp):
+            return {'cat': 0.3, 'dog': 0.7}
+        demo = gr.Interface(fn=image_classifier, inputs="image", outputs="label",
+                            allow_flagging="manual", flagging_callback=hf_writer)
     """
 
     def __init__(
         self,
-        hf_foken: str,
+        hf_token: str,
         dataset_name: str,
         organization: Optional[str] = None,
         private: bool = False,
-        verbose: bool = True,
     ):
         """
-        Params:
-        hf_token (str): The token to use to access the huggingface API.
-        dataset_name (str): The name of the dataset to save the data to, e.g.
-            "image-classifier-1"
-        organization (str): The name of the organization to which to attach
-            the datasets. If None, the dataset attaches to the user only.
-        private (bool): If the dataset does not already exist, whether it
-            should be created as a private dataset or public. Private datasets
-            may require paid huggingface.co accounts
-        verbose (bool): Whether to print out the status of the dataset
-            creation.
+        Parameters:
+            hf_token: The HuggingFace token to use to create (and write the flagged sample to) the HuggingFace dataset.
+            dataset_name: The name of the dataset to save the data to, e.g. "image-classifier-1"
+            organization: The organization to save the dataset under. The hf_token must provide write access to this organization. If not provided, saved under the name of the user corresponding to the hf_token.
+            private: Whether the dataset should be private (defaults to False).
         """
-        self.hf_foken = hf_foken
+        self.hf_token = hf_token
         self.dataset_name = dataset_name
         self.organization_name = organization
         self.dataset_private = private
-        self.verbose = verbose
 
     def setup(self, components: List[Component], flagging_dir: str):
         """
@@ -250,7 +275,7 @@ class HuggingFaceDatasetSaver(FlaggingCallback):
             )
         path_to_dataset_repo = huggingface_hub.create_repo(
             name=self.dataset_name,
-            token=self.hf_foken,
+            token=self.hf_token,
             private=self.dataset_private,
             repo_type="dataset",
             exist_ok=True,
@@ -262,7 +287,7 @@ class HuggingFaceDatasetSaver(FlaggingCallback):
         self.repo = huggingface_hub.Repository(
             local_dir=self.dataset_dir,
             clone_from=path_to_dataset_repo,
-            use_auth_token=self.hf_foken,
+            use_auth_token=self.hf_token,
         )
         self.repo.git_pull()
 

gradio/interface.py

@@ -45,10 +45,10 @@ if TYPE_CHECKING:  # Only import for type checking (is False at runtime).
 @document("launch", "load", "from_pipeline", "integrate")
 class Interface(Blocks):
     """
-    The Interface class is Gradio's main high-level abstraction, and allows you to create a
-    web-based GUI / demo around a machine learning model (or any Python function). You must specify
-    three parameters: (1) the function to create a GUI for (2) the desired input components and
-    (3) the desired output components. Further parameters can be specified to control the appearance
+    Interface is Gradio's main high-level class, and allows you to create a web-based GUI / demo
+    around a machine learning model (or any Python function) in a few lines of code.
+    You must specify three parameters: (1) the function to create a GUI for (2) the desired input components and
+    (3) the desired output components. Additional parameters can be used to control the appearance
     and behavior of the demo.
 
     Example:

website/homepage/src/docs/obj_doc_template.html

@@ -59,6 +59,14 @@
   <p class="text-lg text-gray-500">Supported events: <em>{{ obj["events"] }}</em></p>
   {% endif %}
   
+  {% if obj["example"] %}
+    <h4 class="mt-4 p-3 font-semibold">Example Usage</h4>
+    <div class="codeblock">
+      <pre><code class="lang-python">{{ obj["example"] }}</code></pre>
+    </div>
+  {% endif %}
+
+  {% if (obj["parameters"]|length > 0 and obj["parameters"][0]["name"] != "self") or obj["parameters"]|length > 1 %}
   <table class="table-fixed w-full mt-6 leading-loose">
     <thead class="text-left">
       <tr>
@@ -89,6 +97,8 @@
       {% endfor %}
     </tbody>
   </table>
+  {%endif%}
+  
   {% if is_component and obj["string_shortcuts"] %}
   <table class="mb-4 table-fixed w-full mt-6">
     <thead class="text-left">
@@ -111,12 +121,6 @@
     </tbody>
   </table>
   {% endif %}
-  {% if obj["example"] %}
-    <h4 class="mt-4 p-3 font-semibold">Example Usage</h4>
-    <div class="codeblock">
-      <pre><code class="lang-python">{{ obj["example"] }}</code></pre>
-    </div>
-  {% endif %}
   {% if "fns" in obj and obj["fns"]|length %}
     <h4 class="mt-4 p-3 font-semibold">Methods</h4>
       <div class="flex flex-col gap-8 pl-12">

website/homepage/src/docs/template.html

@@ -14,6 +14,7 @@
             style="min-width: 18%">
         <a class="link current-nav-link px-4 mb-2 block" href="#building_demos">Building Demos</a>
         <a class="thin-link px-4 block" href="#interface">Interface</a>
+        <a class="thin-link px-4 block" href="#flagging">Flagging</a>
         <a class="thin-link px-4 block" href="#combining_interfaces">Combining Interfaces</a>
         <a class="thin-link px-4 block" href="#blocks">Blocks<sup class="text-orange-500">NEW</sup></a>
         <a class="thin-link px-4 block" href="#blocks-utils">Blocks Utilities</a>
@@ -38,14 +39,46 @@
               {% include "docs/obj_doc_template.html" %}
             {% endwith %}
           </section>
+          <section id="flagging" class="pt-2">
+            <h3 class="text-4xl font-light my-4" id="flagging">Flagging</h3>
+            <p class="mt-8 mb-12 text-lg">
+              A Gradio Interface includes a "Flag" button that appears 
+              underneath the output. By default, clicking on the Flag button sends the input and output
+              data back to the machine where the gradio demo is running, and saves it to a CSV log file.
+              But this default behavior can be changed. To set what happens when the Flag button is clicked, 
+              you pass an instance of a subclass of <em>FlaggingCallback</em> to the <em>flagging_callback</em> parameter 
+              in the <em>Interface</em> constructor. You can use one of the <em>FlaggingCallback</em> subclasses 
+              that are listed below, or you can create your own, which lets you do whatever 
+              you want with the data that is being flagged.
+            </p>
+
+            <div class="flex flex-col gap-10">
+            {% for flagging_callback in docs["flagging"] %}
+              {% with obj=flagging_callback, is_class=True, parent="gradio" %}
+                {% include "docs/obj_doc_template.html" %}
+              {% endwith %}
+            {% endfor %}
+            </div>
+            
+            <h4 class="my-2 font-semibold">Flagging Guides</h4>
+              <div class="guides-list grid grid-cols-1 lg:grid-cols-4 gap-4">
+                <a class="guide-box flex lg:col-span-1 flex-col group overflow-hidden relative rounded-xl shadow-sm hover:shadow-alternate transition-shadow my-4 bg-gradient-to-r" target="_blank" href="/using_flagging/">
+                  <div class="flex flex-col p-4 h-min">
+                    <p class="font-semibold group-hover:underline text-l">Flagging</p>
+                  </div>
+                </a>
+              </div>
+        </section>
+
           <section id="combining_interfaces" class="pt-2">
-            <h3 class="text-3xl font-light my-4" id="combining-interfaces">Combining Interfaces</h3>
+            <h3 class="text-4xl font-light my-4" id="combining-interfaces">Combining Interfaces</h3>
             <p class="mt-8 mb-12 text-lg">
               Once you have created several Interfaces, we provide several classes that let you
               start combining them together. For example, you can chain them in <em>Series</em>
               or compare their outputs in <em>Parallel</em> if the inputs and outputs match accordingly.
               You can also display arbitrary Interfaces together in a tabbed layout using <em>TabbedInterface</em>.
             </p>
+            
             <div class="flex flex-col gap-10">
               {% with obj=find_cls("TabbedInterface"), parent="gradio" %}
                 {% include "docs/obj_doc_template.html" %}

website/homepage/src/index/template.html

@@ -73,11 +73,6 @@
           </div>
         </div>
       </div>
-      <a href="https://huggingface.co/spaces/dalle-mini/dalle-mini"
-         class="dall-e-banner flex items-center justify-center py-2 text-smd text-center border-b w-fit mx-auto mt-8 px-6 rounded-full bg-lime-100 hover:bg-lime-200 transition-colors">
-        <div class="uppercase text-xs px-1 mr-2 bg-lime-300 text-gray-800">new</div>
-        Play with 🥑 DALL·E mini on Spaces →
-      </a>
     </div>
     {% include 'index/demos_template.html' %}
     <div class="relative mx-auto container space-y-6 px-4 py-24 md:flex md:space-y-0 md:space-x-8 text-lg">