Guides fixes (#565)

* fixed guides; added contributing guidelines

* updated guide contributing

* fixed flagging guide

* updated organization of readme files

* fixed and brought back readme_template

Co-authored-by: aliabd <ali.si3luwa@gmail.com>

README.md

@@ -2,7 +2,7 @@
 
 #  Welcome to Gradio
 
-Quickly create customizable UI components around your models. Gradio makes it easy for you to "play around" with your model in your browser by dragging-and-dropping in your own images, pasting your own text, recording your own voice, etc. and seeing what the model outputs.  
+Quickly create beautiful user interfaces around your machine learning models. Gradio (pronounced GRAY-dee-oh) makes it easy for you to demo your model in your browser or let people "try it out" by dragging-and-dropping in their own images, pasting text, recording their own voice, etc. and seeing what the model outputs.  
 
 ![Interface montage](website/homepage/src/assets/img/montage.gif)
 
@@ -12,16 +12,18 @@ Gradio is useful for:
 
 * **Deploying** your models quickly with automatic shareable links and getting feedback on model performance
 
-* **Debugging** your model interactively during development using built-in interpretation visualizations for any model
+* **Debugging** your model interactively during development using built-in manipulation and interpretation tools
 
 **You can find an interactive version of the following Getting Started at [https://gradio.app/getting_started](https://gradio.app/getting_started).**
 
 
 ## Getting Started
 
+**Prerequisite**: Python 3.7+ and that's it! 
+
 ### Quick Start
 
-To get Gradio running with a simple example, follow these three steps:
+To get Gradio running with a simple "Hello, World" example, follow these three steps:
 
 <span>1.</span> Install Gradio from pip.
 
@@ -48,15 +50,15 @@ iface.launch()
 
 ![hello_world interface](demo/hello_world/screenshot.gif)
 
-### The Interface
+### Understanding the `Interface` class
 
-Gradio can wrap almost any Python function with an easy-to-use user interface. That function could be anything from a simple tax calculator to a pretrained machine learning model.
+Gradio can wrap almost any Python function with an easy-to-use user interface. In the example above, we saw a simple text-based function. But the function could be anything from image enhancer to a tax calculator to (most commonly) the prediction function of a pretrained machine learning model.
 
 The core  `Interface`  class is initialized with three parameters:
 
 -   `fn`: the function to wrap
--   `inputs`: the input component type(s)
--   `outputs`: the output component type(s)
+-   `inputs`: the input component type(s), e.g. `"image"` or `"audio"` ([see docs for complete list](/docs))
+-   `outputs`: the output component type(s) e.g. `"image"` or `"label"` ([see docs for complete list](/docs))
 
 With these three arguments, we can quickly create interfaces and  `launch()`  them. But what if you want to change how the UI components look or behave?
 
@@ -260,9 +262,9 @@ Note there is no submit button, because the interface resubmits automatically on
 
 ### Using State
 
-Your function may use data that persists beyond a single function call. If the data is something accessible to all function calls, you can create a global variable outside the function call and access it inside the function. For example, you may load a large model outside the function and use it inside the function so that every function call does not need to reload the model.
+Your function may use data that persists beyond a single function call. If the data is something accessible to all function calls and all users, you can create a global variable outside the function call and access it inside the function. For example, you may load a large model outside the function and use it inside the function so that every function call does not need to reload the model.
 
-Another type of data persistence Gradio supports is session state, where data persists across multiple submits within a page load. To store data with this permanence, use `gr.get_state` and `gr.set_state` methods.
+Another type of data persistence Gradio supports is session **state**, where data persists across multiple submits within a page load. However, data is *not* shared between different users of your model. To store data in a session state, you need to do three things: (1) Pass in an extra parameter into your function, which represents the state of the interface. (2) At the end of the function, return the updated value of the state as an extra return value (3) Add the `'state'` input and `'state'` output components when creating your `Interface`. See the chatbot example below: 
 
 ```python
 import random
@@ -307,7 +309,7 @@ iface.launch()
 ```
 ![chatbot interface](demo/chatbot/screenshot.gif)
 
-Notice how the state persists across submits within each page, but the state is not shared between the two pages.
+Notice how the state persists across submits within each page, but the state is not shared between the two pages. Some more points to note: you can pass in a default value to the state parameter, which is used as the initial value of the state. The state must be a something that can be serialized to a JSON format (e.g. a dictionary, a list, or a single value. Typically, objects will not work).  
 
 ### Flagging
 

guides/README.md

@@ -0,0 +1,30 @@
+# Contributing a Guide
+
+Want to help teach Gradio? Consider contributing a Guide! 🤗 
+
+Broadly speaking, there are two types of guides:
+
+* **Use cases**: guides that cover step-by-step how to build a particular type of machine learning demo or app using Gradio. Here's an example: [_Creating a Chatbot_](https://github.com/gradio-app/gradio/blob/master/guides/creating_a_chatbot.md)
+* **Feature explanation**: guides that describe in detail a particular feature of Gradio.  Here's an example: [_Using Flagging_](https://github.com/gradio-app/gradio/blob/master/guides/using_flagging.md)
+
+We encourage you to submit either type of Guide! (Looking for ideas? We may also have open [issues](https://github.com/gradio-app/gradio/issues?q=is%3Aopen+is%3Aissue+label%3Aguides) where users have asked for guides on particular topics)
+
+## Guide Structure
+
+As you can see with the previous examples, Guides are standard markdown documents. They usually:
+* start with an Introduction section describing the topic
+* include subheadings to make articles easy to navigate
+* include real code snippets that make it easy to follow along and implement the Guide
+* include embedded Gradio demos to make them more interactive and provide immediate demonstrations of the topic being discussed. These Gradio demos are hosted on [Hugging Face Spaces](https://huggingface.co/spaces) and are embedded using the standard \<iframe\> tag.
+
+
+## How to Contribute a Guide
+
+1. Clone or fork this `gradio` repo
+2. Add a new markdown document with a descriptive title to the `/guides` folder
+3. Write your Guide in standard markdown! Embed Gradio demos wherever helpful
+4. Add a list of `related_spaces` at the top of the markdown document (see the previously linked Guides for how to do this)
+5. Add 3 `tags` at the top of the markdown document to help users find your guide (again, see the previously linked Guides for how to do this)
+6. Open a PR to have your guide reviewed
+
+That's it! We're looking forward to reading your Guide 🥳

guides/building_a_pictionary_app.md

@@ -5,7 +5,9 @@ tags: SKETCHPAD, LABELS, LIVE
 
 ## Introduction
 
-How well can an algorithm guess what you're drawing? A few years ago, Google released the **Quick Draw** dataset, which contains drawings made by humans of a variety of every objects. Researchers have used this dataset to train models to guess Pictionary-style drawings. Such models are perfect to use with Gradio's *sketchpad* input, so in this tutorial we will build a Pictionary web application using Gradio. We will be able to build the whole web application in Python, and will look like this (try drawing something!):
+How well can an algorithm guess what you're drawing? A few years ago, Google released the **Quick Draw** dataset, which contains drawings made by humans of a variety of every objects. Researchers have used this dataset to train models to guess Pictionary-style drawings. 
+
+Such models are perfect to use with Gradio's *sketchpad* input, so in this tutorial we will build a Pictionary web application using Gradio. We will be able to build the whole web application in Python, and will look like this (try drawing something!):
 
 <iframe src="https://hf.space/gradioiframe/abidlabs/draw2/+" frameBorder="0" height="450" title="Gradio app" class="container p-0 flex-grow space-iframe" allow="accelerometer; ambient-light-sensor; autoplay; battery; camera; document-domain; encrypted-media; fullscreen; geolocation; gyroscope; layout-animations; legacy-image-formats; magnetometer; microphone; midi; oversized-images; payment; picture-in-picture; publickey-credentials-get; sync-xhr; usb; vr ; wake-lock; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-same-origin allow-scripts allow-downloads"></iframe>
 

guides/creating_a_chatbot.md

@@ -2,9 +2,12 @@
 
 related_spaces: https://huggingface.co/spaces/abidlabs/chatbot-minimal, https://huggingface.co/spaces/ThomasSimonini/Chat-with-Gandalf-GPT-J6B, https://huggingface.co/spaces/gorkemgoknar/moviechatbot, https://huggingface.co/spaces/Kirili4ik/chat-with-Kirill
 tags: NLP, TEXT, HTML
+
 ## Introduction
 
-Chatbots are widely studied in natural language processing (NLP) research and are a common use case of NLP in industry. Because chatbots are designed to be used directly by customers and end users, it is important to validate that chatbots are behaving as expected when confronted with a wide variety of input prompts. Using `gradio`, you can easily build a demo of your chatbot model and share that with a testing team, or test it yourself using an intuitive chatbot GUI.
+Chatbots are widely studied in natural language processing (NLP) research and are a common use case of NLP in industry. Because chatbots are designed to be used directly by customers and end users, it is important to validate that chatbots are behaving as expected when confronted with a wide variety of input prompts. 
+
+Using `gradio`, you can easily build a demo of your chatbot model and share that with a testing team, or test it yourself using an intuitive chatbot GUI.
 
 This tutorial will show how to take a pretrained chatbot model and deploy it with a Gradio interface in 4 steps. The live chatbot interface that we create will look something like this (try it!):
 
@@ -139,7 +142,7 @@ Notice that we have also added a placeholder to the input `text` component by in
 
 And you're done! That's all the code you need to build an interface for your chatbot model. Here are some references that you may find useful:
 
-* Gradio's ["Getting Started" guide]()
-* The [chatbot demo]() and [complete code]() (on Hugging Face Spaces)
+* Gradio's ["Getting Started" guide](https://gradio.app/getting_started/)
+* The final [chatbot demo](https://huggingface.co/spaces/abidlabs/chatbot-stylized) and [complete code](https://huggingface.co/spaces/abidlabs/chatbot-stylized/tree/main) (on Hugging Face Spaces)
 
 

guides/using_flagging.md

@@ -3,31 +3,36 @@
 related_spaces: https://huggingface.co/spaces/aliabd/calculator-flagging-crowdsourced, https://huggingface.co/spaces/aliabd/calculator-flagging-options, https://huggingface.co/spaces/aliabd/calculator-flag-basic
 tags: FLAGGING, DATA
 
-## The `flag` button 
+## Introduction
 
-Underneath the output interfaces, there is a button marked `flag`. When a user testing your model sees input with interesting output, such as erroneous or unexpected model behaviour, they can flag the input for the interface creator to review. 
+When you deploy or demo a machine learning model, you may find that it behaves differently than how you expected (e.g. the model makes an incorrect prediction) when a user tries it with their own data. Capturing these "hard" data points is important because it allows you to make you machine learning model more reliable and robust.
+
+Gradio simplifies the collection of this data by including a FLAG button with every `Interface`. This allows your user or tester to easily send data back to you, whether the model is running locally or has been shared by setting `share=True`. 
+
+## The **Flag** button 
+
+Underneath the output interfaces, there is a button marked **Flag**. When a user testing your model sees input with interesting output, such as erroneous or unexpected model behaviour, they can flag the input for the interface creator to review. 
 
 ![flag button](website/src/assets/img/guides/using_flagging/flag_button.gif)
 
 There are four parameters `gr.Interface` that control how flagging works. We will go over them in greater detail.
 
-* `allow_flagging`: 
-    * This parameter can be set to either `"manual"`, `"auto"`, or `"never"`.                 
+* `allow_flagging`: this parameter can be set to either `"manual"`, `"auto"`, or `"never"`.                 
     * `manual`: users will see a button to flag, and events are only flagged when it's clicked.
     * `auto`: users will not see a button to flag, but every event will be flagged automatically. 
     * `never`: users will not see a button to flag, and no event will be flagged. 
-* `flagging_options`:
-    * This parameter takes a list of strings.
-    * If provided, allows user to select from a list of options when flagging. Only applies if `allow_flagging` is `"manual"`.
+* `flagging_options`: this parameter can be either `None` (default) or a list of strings.
+    * If `None`, then the user simply clicks on the **Flag** button and no additional options are shown.
+    * If a list of strings are provided, this allows user to select from a list of options when flagging. Only applies if `allow_flagging` is `"manual"`.
     * The chosen option is then piped along with the input and output.
-* `flagging_dir`: 
-    * This parameter takes a string.
-    * What to name the directory where flagged data is stored.
-* `flagging_callback`: 
+* `flagging_dir`: this parameter takes a string.
+    * It represents what to name the directory where flagged data is stored.
+* `flagging_callback`: this parameter takes an instance of a subclass of the `FlaggingCallback` class
     * Using this parameter allows you to write custom code that gets run when the flag button is clicked
-    * One example is setting it to `gr.HuggingFaceDatasetSaver` which can allow you to pipe any flagged data into a HuggingFace Dataset.
+    * By default, this is set to an instance of `gr.CSVLogger`
+    * One example is setting it to an instance of `gr.HuggingFaceDatasetSaver` which can allow you to pipe any flagged data into a HuggingFace Dataset.
 
-## The data:
+## What happens to flagged data?
 
 Within the directory provided by the `flagging_dir` argument, a CSV file will log the flagged data. 
 

readme_template.md

@@ -17,7 +17,7 @@ Gradio is useful for:
 **You can find an interactive version of the following Getting Started at [https://gradio.app/getting_started](https://gradio.app/getting_started).**
 
 {% with code=code, demos=demos %}
-{% include "getting_started.md" %}
+{% include "guides/getting_started.md" %}
 {% endwith %}
 
 ##  System Requirements:

render_readme.py

@@ -41,7 +41,7 @@ class GuidesLoader(BaseLoader):
         return source, path, lambda: mtime == getmtime(path)
 
 
-readme_template = Environment(loader=GuidesLoader("guides")).get_template(
+readme_template = Environment(loader=GuidesLoader(".")).get_template(
     README_TEMPLATE
 )
 output_readme = readme_template.render(code=code, demos=demos)

website/homepage/render_html.py

@@ -43,7 +43,7 @@ def render_index():
 
 guides = []
 for guide in sorted(os.listdir(GRADIO_GUIDES_DIR)):
-    if "template" in guide:
+    if guide.lower() in ["getting_started.md", "readme.md"]:
         continue
     guide_name = guide[:-3]
     pretty_guide_name = " ".join(