Document Blocks methods (#3427)

* document launch, queue and integrate in blocks

* seperate example usages for interface vs blocks methods

* changelog

* fix lint

---------

Co-authored-by: Abubakar Abid <abubakar@huggingface.co>

CHANGELOG.md

@@ -15,10 +15,11 @@ No changes to highlight.
 - Add Chinese README by [@uanu2002](https://github.com/uanu2002) in [PR 3394](https://github.com/gradio-app/gradio/pull/3394)
 - Adds documentation for web components by [@abidlabs](https://github.com/abidlabs) in [PR 3407](https://github.com/gradio-app/gradio/pull/3407)
 - Fixed link in Chinese readme  by [@eltociear](https://github.com/eltociear) in [PR 3417](https://github.com/gradio-app/gradio/pull/3417)
+- Document Blocks methods by [@aliabd](https://github.com/aliabd) in [PR 3427](https://github.com/gradio-app/gradio/pull/3427)
 
 ## Testing and Infrastructure Changes:
 - Fixes tests that were failing locally but passing on CI by [@abidlabs](https://github.com/abidlabs) in [PR 3411](https://github.com/gradio-app/gradio/pull/3411)
-- Remove codecov from the repo [@aliabd](https://github.com/aliabd) in [PR 3415](https://github.com/gradio-app/gradio/pull/3415)
+- Remove codecov from the repo by [@aliabd](https://github.com/aliabd) in [PR 3415](https://github.com/gradio-app/gradio/pull/3415)
 
 ## Breaking Changes:
 

gradio/blocks.py

@@ -404,7 +404,7 @@ def convert_component_dict_to_list(
     return predictions
 
 
-@document("load")
+@document("launch", "queue", "integrate", "load")
 class Blocks(BlockContext):
     """
     Blocks is Gradio's low-level API that allows you to create more custom web
@@ -1226,8 +1226,14 @@ class Blocks(BlockContext):
             default_enabled: Deprecated and has no effect.
             api_open: If True, the REST routes of the backend will be open, allowing requests made directly to those endpoints to skip the queue.
             max_size: The maximum number of events the queue will store at any given moment. If the queue is full, new events will not be added and a user will receive a message saying that the queue is full. If None, the queue size will be unlimited.
-        Example:
-            demo = gr.Interface(gr.Textbox(), gr.Image(), image_generator)
+        Example: (Blocks)
+            with gr.Blocks() as demo:
+                button = gr.Button(label="Generate Image")
+                button.click(fn=image_generator, inputs=gr.Textbox(), outputs=gr.Image())
+            demo.queue(concurrency_count=3)
+            demo.launch()
+        Example: (Interface)
+            demo = gr.Interface(image_generator, gr.Textbox(), gr.Image())
             demo.queue(concurrency_count=3)
             demo.launch()
         """
@@ -1310,7 +1316,15 @@ class Blocks(BlockContext):
             app: FastAPI app object that is running the demo
             local_url: Locally accessible link to the demo
             share_url: Publicly accessible link to the demo (if share=True, otherwise None)
-        Example:
+        Example: (Blocks)
+            import gradio as gr
+            def reverse(text):
+                return text[::-1]
+            with gr.Blocks() as demo:
+                button = gr.Button(value="Reverse")
+                button.click(reverse, gr.Textbox(), gr.Textbox())
+            demo.launch(share=True, auth=("username", "password"))
+        Example:  (Interface)
             import gradio as gr
             def reverse(text):
                 return text[::-1]

gradio/documentation.py

@@ -34,7 +34,7 @@ def document(*fns):
     return inner_doc
 
 
-def document_fn(fn: Callable) -> Tuple[str, List[Dict], Dict, str | None]:
+def document_fn(fn: Callable, cls) -> Tuple[str, List[Dict], Dict, str | None]:
     """
     Generates documentation for any function.
     Parameters:
@@ -54,8 +54,12 @@ def document_fn(fn: Callable) -> Tuple[str, List[Dict], Dict, str | None]:
         line = line.rstrip()
         if line == "Parameters:":
             mode = "parameter"
-        elif line == "Example:":
+        elif line.startswith("Example:"):
             mode = "example"
+            if "(" in line and ")" in line:
+                c = line.split("(")[1].split(")")[0]
+                if c != cls.__name__:
+                    mode = "ignore"
         elif line == "Returns:":
             mode = "return"
         else:
@@ -158,7 +162,7 @@ def generate_documentation():
         documentation[mode] = []
         for cls, fns in class_list:
             fn_to_document = cls if inspect.isfunction(cls) else cls.__init__
-            _, parameter_doc, return_doc, _ = document_fn(fn_to_document)
+            _, parameter_doc, return_doc, _ = document_fn(fn_to_document, cls)
             cls_description, cls_tags, cls_example = document_cls(cls)
             cls_documentation = {
                 "class": cls,
@@ -177,7 +181,7 @@ def generate_documentation():
                     parameter_docs,
                     return_docs,
                     examples_doc,
-                ) = document_fn(fn)
+                ) = document_fn(fn, cls)
                 cls_documentation["fns"].append(
                     {
                         "fn": fn,