add documentation for awaitable button clicks

nicegui/elements/button.py

@@ -37,6 +37,7 @@ class Button(TextElement, DisableableElement):
         self._props['label'] = text
 
     async def clicked(self):
+        '''Await this coroutine to delay execution until the button is clicked.'''
         event = asyncio.Event()
         self.on('click', event.set)
         await self.client.connected()

website/more_documentation/button_documentation.py

@@ -1,5 +1,18 @@
 from nicegui import ui
 
+from ..documentation_tools import text_demo
+
 
 def main_demo() -> None:
     ui.button('Click me!', on_click=lambda: ui.notify(f'You clicked me!'))
+
+
+def more() -> None:
+    @text_demo('Await button click', '''
+        Sometimes it is convenient to wait for a button click before continuing the execution.
+    ''')
+    async def await_button_click() -> None:
+        # @ui.page('/')
+        # async def index():
+            await ui.button('What comes next?').clicked()
+            ui.label('Bam! This is the future!')