Merge branch 'main' of github.com:zauberzeug/nicegui

website/documentation/content/doc/__init__.py

@@ -1,4 +1,4 @@
-from .api import demo, get_page, intro, reference, registry, text, title, ui
+from .api import demo, extra_column, get_page, intro, reference, registry, text, title, ui
 
 __all__ = [
     'demo',
@@ -9,4 +9,5 @@
     'title',
     'ui',
     'get_page',
+    'extra_column',
 ]

website/documentation/content/doc/api.py

@@ -130,6 +130,12 @@ def reference(element: type, *,
     _get_current_page().parts.append(DocumentationPart(title=title, reference=element))
 
 
+def extra_column(function: Callable) -> Callable:
+    """Add an extra column to the current documentation page."""
+    _get_current_page().extra_column = function
+    return function
+
+
 def _find_attribute(obj: Any, name: str) -> Optional[str]:
     for attr in dir(obj):
         if attr.lower().replace('_', '') == name.lower().replace('_', ''):

website/documentation/content/doc/page.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field
-from typing import List, Optional
+from typing import Callable, List, Optional
 
 from nicegui.dataclasses import KWONLY_SLOTS
 
@@ -13,6 +13,7 @@ class DocumentationPage:
     subtitle: Optional[str] = None
     back_link: Optional[str] = None
     parts: List[DocumentationPart] = field(default_factory=list)
+    extra_column: Optional[Callable] = None
 
     @property
     def heading(self) -> str:

website/documentation/content/overview.py

@@ -39,6 +39,40 @@
     Or if you prefer, almost anything can be styled with CSS.
 ''')
 
+doc.text('Actions', '''
+    NiceGUI runs an event loop to handle user input and other events like timers and keyboard bindings.
+    You can write asynchronous functions for long-running tasks to keep the UI responsive.
+    The _Actions_ section covers how to work with events.
+''')
+
+doc.text('Implementation', '''
+    NiceGUI is implemented with HTML components served by an HTTP server (FastAPI), even for native windows.
+    If you already know HTML, everything will feel very familiar.
+    If you don't know HTML, that's fine too!
+    NiceGUI abstracts away the details, so you can focus on creating beautiful interfaces without worrying about how they are implemented.
+''')
+
+doc.text('Running NiceGUI Apps', '''
+    There are several options for deploying NiceGUI.
+    By default, NiceGUI runs a server on localhost and runs your app as a private web page on the local machine.
+    When run this way, your app appears in a web browser window.
+    You can also run NiceGUI in a native window separate from a web browser.
+    Or you can run NiceGUI on a server that handles many clients - the website you're reading right now is served from NiceGUI.
+
+    After creating your app pages with components, you call `ui.run()` to start the NiceGUI server.
+    Optional parameters to `ui.run` set things like the network address and port the server binds to, 
+    whether the app runs in native mode, initial window size, and many other options.
+    The section _Configuration and Deployment_ covers the options to the `ui.run()` function and the FastAPI framework it is based on.
+''')
+
+doc.text('Customization', '''
+    If you want more customization in your app, you can use the underlying Tailwind classes and Quasar components
+    to control the style or behavior of your components.
+    You can also extend the available components by subclassing existing NiceGUI components or importing new ones from Quasar.
+    All of this is optional.
+    Out of the box, NiceGUI provides everything you need to make modern, stylish, responsive user interfaces.
+''')
+
 tiles = [
     (section_text_elements, '''
         Elements like `ui.label`, `ui.markdown` and `ui.html` can be used to display text and other content.
@@ -73,49 +107,13 @@
 ]
 
 
-@doc.ui
+@doc.extra_column
 def create_tiles():
-    with ui.grid().classes('grid-cols-[1fr] md:grid-cols-[1fr_1fr] xl:grid-cols-[1fr_1fr_1fr]'):
-        for documentation, description in tiles:
-            page = doc.get_page(documentation)
-            with ui.link(target=f'/documentation/{page.name}') \
-                    .classes('bg-[#5898d420] p-4 self-stretch rounded flex flex-col gap-2') \
-                    .style('box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1)'):
-                if page.title:
-                    ui.label(page.title.replace('*', '')).classes(replace='text-2xl')
-                ui.markdown(description).classes(replace='bold-links arrow-links')
-
-
-doc.text('Actions', '''
-    NiceGUI runs an event loop to handle user input and other events like timers and keyboard bindings.
-    You can write asynchronous functions for long-running tasks to keep the UI responsive.
-    The _Actions_ section covers how to work with events.
-''')
-
-doc.text('Implementation', '''
-    NiceGUI is implemented with HTML components served by an HTTP server (FastAPI), even for native windows.
-    If you already know HTML, everything will feel very familiar.
-    If you don't know HTML, that's fine too!
-    NiceGUI abstracts away the details, so you can focus on creating beautiful interfaces without worrying about how they are implemented.
-''')
-
-doc.text('Running NiceGUI Apps', '''
-    There are several options for deploying NiceGUI.
-    By default, NiceGUI runs a server on localhost and runs your app as a private web page on the local machine.
-    When run this way, your app appears in a web browser window.
-    You can also run NiceGUI in a native window separate from a web browser.
-    Or you can run NiceGUI on a server that handles many clients - the website you're reading right now is served from NiceGUI.
-
-    After creating your app pages with components, you call `ui.run()` to start the NiceGUI server.
-    Optional parameters to `ui.run` set things like the network address and port the server binds to, 
-    whether the app runs in native mode, initial window size, and many other options.
-    The section _Configuration and Deployment_ covers the options to the `ui.run()` function and the FastAPI framework it is based on.
-''')
-
-doc.text('Customization', '''
-    If you want more customization in your app, you can use the underlying Tailwind classes and Quasar components
-    to control the style or behavior of your components.
-    You can also extend the available components by subclassing existing NiceGUI components or importing new ones from Quasar.
-    All of this is optional.
-    Out of the box, NiceGUI provides everything you need to make modern, stylish, responsive user interfaces.
-''')
+    for documentation, description in tiles:
+        page = doc.get_page(documentation)
+        with ui.link(target=f'/documentation/{page.name}') \
+                .classes('bg-[#5898d420] p-4 self-stretch rounded flex flex-col gap-2') \
+                .style('box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1)'):
+            if page.title:
+                ui.label(page.title.replace('*', '')).classes(replace='text-2xl')
+            ui.markdown(description).classes(replace='bold-links arrow-links')

website/documentation/rendering.py

@@ -13,29 +13,27 @@
 def render_page(documentation: DocumentationPage, *, with_menu: bool = True) -> None:
     """Render the documentation."""
 
-    # header
-    add_head_html()
-    add_header()
-    ui.add_head_html('<style>html {scroll-behavior: auto;}</style>')
-
     # menu
     if with_menu:
         with ui.left_drawer() \
                 .classes('column no-wrap gap-1 bg-[#eee] dark:bg-[#1b1b1b] mt-[-20px] px-8 py-20') \
-                .style('height: calc(100% + 20px) !important'):
+                .style('height: calc(100% + 20px) !important') as menu:
             if documentation.back_link:
                 ui.markdown(f'[← back]({documentation.back_link or "."})').classes('bold-links')
             else:
                 ui.markdown('[← Overview](/documentation)').classes('bold-links')
             ui.markdown(f'**{documentation.heading.replace("*", "")}**').classes('mt-4')
+    else:
+        menu = None
 
-    # content
-    with ui.column().classes('w-full p-8 lg:p-16 max-w-[1250px] mx-auto'):
+    # header
+    add_head_html()
+    add_header(menu)
+    ui.add_head_html('<style>html {scroll-behavior: auto;}</style>')
 
-        # heading
+    # content
+    def render_content():
         section_heading(documentation.subtitle or '', documentation.heading)
-
-        # parts
         for part in documentation.parts:
             if part.title:
                 if part.link_target:
@@ -57,3 +55,12 @@ def render_page(documentation: DocumentationPage, *, with_menu: bool = True) ->
                 generate_class_doc(part.reference)
             if part.link:
                 ui.markdown(f'See [more...]({part.link})').classes('bold-links arrow-links')
+    with ui.column().classes('w-full p-8 lg:p-16 max-w-[1250px] mx-auto'):
+        if documentation.extra_column:
+            with ui.grid().classes('grid-cols-[2fr_1fr] max-[600px]:grid-cols-[1fr] gap-x-8 gap-y-16'):
+                with ui.column().classes('w-full'):
+                    render_content()
+                with ui.column():
+                    documentation.extra_column()
+        else:
+            render_content()

website/header.py

@@ -37,7 +37,7 @@ def add_header(menu: Optional[ui.left_drawer] = None) -> None:
         if menu:
             ui.button(on_click=menu.toggle, icon='menu').props('flat color=white round').classes('lg:hidden')
         with ui.link(target='/').classes('row gap-4 items-center no-wrap mr-auto'):
-            svg.face().classes('w-8 stroke-white stroke-2 max-[550px]:hidden')
+            svg.face().classes('w-8 stroke-white stroke-2 max-[610px]:hidden')
             svg.word().classes('w-24')
 
         with ui.row().classes('max-[1050px]:hidden'):
@@ -47,22 +47,22 @@ def add_header(menu: Optional[ui.left_drawer] = None) -> None:
         search = Search()
         search.create_button()
 
-        with ui.element().classes('max-[360px]:hidden'):
+        with ui.element().classes('max-[420px]:hidden'):
             ui.button(icon='dark_mode', on_click=lambda: dark_mode.set_value(None)) \
                 .props('flat fab-mini color=white').bind_visibility_from(dark_mode, 'value', value=True)
             ui.button(icon='light_mode', on_click=lambda: dark_mode.set_value(True)) \
                 .props('flat fab-mini color=white').bind_visibility_from(dark_mode, 'value', value=False)
             ui.button(icon='brightness_auto', on_click=lambda: dark_mode.set_value(False)) \
                 .props('flat fab-mini color=white').bind_visibility_from(dark_mode, 'value', lambda mode: mode is None)
 
-        with ui.link(target='https://discord.gg/TEpFeAaF4f').classes('max-[455px]:hidden').tooltip('Discord'):
+        with ui.link(target='https://discord.gg/TEpFeAaF4f').classes('max-[515px]:hidden').tooltip('Discord'):
             svg.discord().classes('fill-white scale-125 m-1')
-        with ui.link(target='https://www.reddit.com/r/nicegui/').classes('max-[405px]:hidden').tooltip('Reddit'):
+        with ui.link(target='https://www.reddit.com/r/nicegui/').classes('max-[465px]:hidden').tooltip('Reddit'):
             svg.reddit().classes('fill-white scale-125 m-1')
-        with ui.link(target='https://github.com/zauberzeug/nicegui/').classes('max-[305px]:hidden').tooltip('GitHub'):
+        with ui.link(target='https://github.com/zauberzeug/nicegui/').classes('max-[365px]:hidden').tooltip('GitHub'):
             svg.github().classes('fill-white scale-125 m-1')
 
-        add_star().classes('max-[490px]:hidden')
+        add_star().classes('max-[550px]:hidden')
 
         with ui.row().classes('min-[1051px]:hidden'):
             with ui.button(icon='more_vert').props('flat color=white round'):