Added docs on gr.Examples (#6412)

* added docs on gr.Examples change

* add changeset

* docstrings

* Update guides/03_building-with-blocks/01_blocks-and-event-listeners.md

Co-authored-by: Freddy Boulton <alfonsoboulton@gmail.com>

* typo

---------

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>
Co-authored-by: Freddy Boulton <alfonsoboulton@gmail.com>

.changeset/chubby-clowns-refuse.md

@@ -0,0 +1,5 @@
+---
+"gradio": patch
+---
+
+fix:Added docs on gr.Examples

gradio/CHANGELOG.md

@@ -143,7 +143,8 @@ Gradio 4.0 is a new major version, and includes breaking changes from 3.x. Here'
 * Removes `deprecation.py` -- this was designed for internal usage so unlikely to break gradio apps
 * Moves save to cache methods from component methods to standalone functions in processing_utils
 * Renames `source` param in `gr.Audio` and `gr.Video` to `sources`
-* Removes `show_edit_button` param from `gr.Audio``
+* Removes `show_edit_button` param from `gr.Audio`
+* The `Image` component with any tool (`gr.Image(tool=...)`) has temporarily been removed from 4.0. It will be replaced with a separate `ImageEditor` component soon.
 
 
 **Other changes related to the `gradio` library**:
@@ -158,7 +159,7 @@ Gradio 4.0 is a new major version, and includes breaking changes from 3.x. Here'
 * Changes the format of flagged data to json instead of filepath for media and chatbot
 * Removes `gr.Series` and `gr.Parallel`
 * All API endpoints are named by deafult. If `api_name=None`, the api name is the name of the python function.
-
+* If you click on examples in a `gr.Examples`, the component will not only update its value, but it will revert its properties to the ones it was constructed with. 
 
 **Changes related to the Client libraries**:
 

gradio/helpers.py

@@ -111,15 +111,15 @@ def __init__(
         Parameters:
             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 but it should be within the directory with the python file running the gradio app. If there are multiple input components and a directory is provided, a log.csv file must be present in the directory to link corresponding inputs.
             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.
+            outputs: optionally, provide the component or list of components corresponding to the output of the examples. Required if `cache_examples` is True.
+            fn: optionally, provide the function to run to generate the outputs corresponding to the examples. Required if `cache_examples` is True.
             cache_examples: if True, caches examples for fast runtime. If True, then `fn` and `outputs` must be provided. If `fn` is a generator function, then the last yielded value will be used as the output.
             examples_per_page: how many examples to show per page.
             label: the label to use for the examples component (by default, "Examples")
             elem_id: an optional string that is assigned as the id of this component in the HTML DOM.
             run_on_click: if cache_examples is False, clicking on an example does not run the function when an example is clicked. Set this to True to run the function when an example is clicked. Has no effect if cache_examples is True.
-            preprocess: if True, preprocesses the example input before running the prediction function and caching the output. Only applies if cache_examples is True.
-            postprocess: if True, postprocesses the example output after running the prediction function and before caching. Only applies if cache_examples is True.
+            preprocess: if True, preprocesses the example input before running the prediction function and caching the output. Only applies if `cache_examples` is True.
+            postprocess: if True, postprocesses the example output after running the prediction function and before caching. Only applies if `cache_examples` is True.
             api_name: Defines how the event associated with clicking on the examples appears in the API docs. Can be a string or False. If set to a string, the endpoint will be exposed in the API docs with the given name. If False, the endpoint will not be exposed in the API docs and downstream apps (including those that `gr.load` this app) will not be able to use the example function.
             batch: If True, then the function should process a batch of inputs, meaning that it should accept a list of input values for each parameter. Used only if cache_examples is True.
         """

guides/03_building-with-blocks/01_blocks-and-event-listeners.md

@@ -129,6 +129,26 @@ $demo_blocks_essay_simple
 
 See how we can configure the Textbox itself through a new `gr.Textbox()` method. The `value=` argument can still be used to update the value along with Component configuration. Any arguments we do not set will use their previous values.
 
+## Examples
+
+Just like with `gr.Interface`, you can also add examples for your functions when you are working with `gr.Blocks`. In this case, instantiate a `gr.Examples` similar to how you would instantiate any other component. The constructor of `gr.Examples` takes two required arguments:
+
+* `examples`: a nested list of examples, in which the outer list consists of examples and each inner list consists of an input corresponding to each input component
+* `inputs`: the component or list of components that should be populated when the examples are clicked
+
+You can also set `cache_examples=True` similar to `gr.Interface`, in which case two additional arguments must be provided:
+
+* `outputs`: the component or list of components corresponding to the output of the examples
+* `fn`: the function to run to generate the outputs corresponding to the examples
+
+Here's an example showing how to use `gr.Examples` in a `gr.Blocks` app:
+
+$code_calculator_blocks
+
+**Note**: In Gradio 4.0 or later, when you click on examples, not only does the value of the input component update to the example value, but the component's configuration also reverts to the properties with which you constructed the component. This ensures that the examples are compatible with the component even if its configuration has been changed. 
+
+
+
 ## Running Events Consecutively
 
 You can also run events consecutively by using the `then` method of an event listener. This will run an event after the previous event has finished running. This is useful for running events that update components in multiple steps.