start to implement section intros

main.py

@@ -409,7 +409,18 @@ def documentation_page() -> None:
     ui.add_head_html('<style>html {scroll-behavior: auto;}</style>')
     with ui.column().classes('w-full p-8 lg:p-16 max-w-[1250px] mx-auto'):
         section_heading('Reference, Demos and more', '*NiceGUI* Documentation')
-        documentation.create_full()
+        documentation.create_overview()
+
+
+@ui.page('/documentation/section_{name}')
+def documentation_section(name: str) -> None:
+    add_head_html()
+    with side_menu() as menu:
+        ui.markdown('[← back](/documentation)').classes('bold-links')
+    add_header(menu)
+    ui.add_head_html('<style>html {scroll-behavior: auto;}</style>')
+    with ui.column().classes('w-full p-8 lg:p-16 max-w-[1250px] mx-auto'):
+        documentation.create_section(name)
 
 
 @ui.page('/documentation/{name}')

website/documentation/__init__.py

@@ -1,5 +1,5 @@
 from . import more
-from .content import create_full
+from .content import create_overview, create_section
 from .demo import bash_window, browser_window, python_window
 from .intro import create_intro
 from .tools import create_anchor_name, element_demo, generate_class_doc
@@ -8,7 +8,8 @@ __all__ = [
     'bash_window',
     'browser_window',
     'create_anchor_name',
-    'create_full',
+    'create_overview',
+    'create_section',
     'more',
     'create_intro',
     'element_demo',

website/documentation/content.py

@@ -1,32 +1,32 @@
+from typing import Dict
+
+from .section import Section
 from .sections import (action_events, audiovisual_elements, binding_properties, configuration_deployment, controls,
                        data_elements, page_layout, styling_appearance, text_elements)
 from .tools import heading
 
-
-def create_full() -> None:
-    heading('Text Elements')
-    text_elements.content()
-
-    heading('Controls')
-    controls.content()
-
-    heading('Audiovisual Elements')
-    audiovisual_elements.content()
-
-    heading('Data Elements')
-    data_elements.content()
-
-    heading('Binding Properties')
-    binding_properties.content()
-
-    heading('Page Layout')
-    page_layout.content()
-
-    heading('Styling and Appearance')
-    styling_appearance.content()
-
-    heading('Action Events')
-    action_events.content()
-
-    heading('Configuration and Deployment')
-    configuration_deployment.content()
+SECTIONS: Dict[str, Section] = {
+    section.name: section
+    for section in [
+        text_elements,
+        controls,
+        audiovisual_elements,
+        data_elements,
+        binding_properties,
+        page_layout,
+        styling_appearance,
+        action_events,
+        configuration_deployment,
+    ]
+}
+
+
+def create_overview() -> None:
+    for section in SECTIONS.values():
+        section.intro()
+
+
+def create_section(name: str) -> None:
+    section = SECTIONS[name]
+    heading(section.title)
+    section.content()

website/documentation/intro.py

@@ -1,11 +1,11 @@
 from nicegui import ui
 
-from .tools import intro_demo
+from .tools import main_page_demo
 
 
 def create_intro() -> None:
-    @intro_demo('Styling',
-                'While having reasonable defaults, you can still modify the look of your app with CSS as well as Tailwind and Quasar classes.')
+    @main_page_demo('Styling',
+                    'While having reasonable defaults, you can still modify the look of your app with CSS as well as Tailwind and Quasar classes.')
     def formatting_demo():
         ui.icon('thumb_up')
         ui.markdown('This is **Markdown**.')
@@ -16,8 +16,8 @@ def create_intro() -> None:
             ui.label('Quasar').classes('q-ml-xl')
         ui.link('NiceGUI on GitHub', 'https://github.com/zauberzeug/nicegui')
 
-    @intro_demo('Common UI Elements',
-                'NiceGUI comes with a collection of commonly used UI elements.')
+    @main_page_demo('Common UI Elements',
+                    'NiceGUI comes with a collection of commonly used UI elements.')
     def common_elements_demo():
         from nicegui.events import ValueChangeEventArguments
 
@@ -35,8 +35,8 @@ def create_intro() -> None:
             ui.select(['One', 'Two'], value='One', on_change=show)
         ui.link('And many more...', '/documentation').classes('mt-8')
 
-    @intro_demo('Value Binding',
-                'Binding values between UI elements and data models is built into NiceGUI.')
+    @main_page_demo('Value Binding',
+                    'Binding values between UI elements and data models is built into NiceGUI.')
     def binding_demo():
         class Demo:
             def __init__(self):

website/documentation/section.py

@@ -0,0 +1,18 @@
+from typing import Protocol
+
+
+class Section(Protocol):
+
+    @property
+    def name(self) -> str:
+        ...
+
+    @property
+    def title(self) -> str:
+        ...
+
+    def intro(self) -> None:
+        ...
+
+    def content(self) -> None:
+        ...

website/documentation/sections/action_events.py

@@ -2,6 +2,13 @@ from nicegui import app, ui
 
 from ..tools import element_demo, load_demo, subheading, text_demo
 
+name = 'action_events'
+title = 'Action Events'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     load_demo(ui.timer)

website/documentation/sections/audiovisual_elements.py

@@ -2,6 +2,13 @@ from nicegui import ui
 
 from ..tools import load_demo, text_demo
 
+name = 'audiovisual_elements'
+title = 'Audiovisual Elements'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     load_demo(ui.image)

website/documentation/sections/binding_properties.py

@@ -1,5 +1,12 @@
 from ..tools import load_demo
 
+name = 'binding_properties'
+title = 'Binding Properties'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     load_demo('bindings')

website/documentation/sections/configuration_deployment.py

@@ -3,6 +3,13 @@ from nicegui import ui
 from ..demo import bash_window, python_window
 from ..tools import load_demo, subheading, text_demo
 
+name = 'configuration_deployment'
+title = 'Configuration & Deployment'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     @text_demo('URLs', '''

website/documentation/sections/controls.py

@@ -2,6 +2,13 @@ from nicegui import ui
 
 from ..tools import load_demo
 
+name = 'controls'
+title = 'Controls'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     load_demo(ui.button)

website/documentation/sections/data_elements.py

@@ -2,6 +2,13 @@ from nicegui import optional_features, ui
 
 from ..tools import load_demo
 
+name = 'data_elements'
+title = 'Data Elements'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     load_demo(ui.table)

website/documentation/sections/page_layout.py

@@ -2,6 +2,13 @@ from nicegui import ui
 
 from ..tools import load_demo, text_demo
 
+name = 'page_layout'
+title = 'Page Layout'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     @text_demo('Auto-context', '''

website/documentation/sections/pages_routing.py

@@ -6,6 +6,13 @@ from ..tools import element_demo, load_demo, subheading, text_demo
 
 CONSTANT_UUID = str(uuid.uuid4())
 
+name = 'pages_routing'
+title = 'Pages & Routing'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     load_demo(ui.page)

website/documentation/sections/styling_appearance.py

@@ -3,6 +3,13 @@ from nicegui import events, ui
 from ..demo import browser_window, python_window
 from ..tools import load_demo, subheading, text_demo
 
+name = 'styling_appearance'
+title = 'Styling & Appearance'
+
+
+def intro() -> None:
+    ...
+
 
 def content() -> None:
     @text_demo('Styling', '''

website/documentation/sections/text_elements.py

@@ -1,6 +1,21 @@
 from nicegui import ui
 
-from ..tools import load_demo
+from ..tools import load_demo, section_intro_demo
+
+name = 'text_elements'
+title = 'Text Elements'
+
+
+def intro() -> None:
+    @section_intro_demo(name, title, '''
+        NiceGUI provides a set of text elements to display text and other content.
+        The most basic element is the `ui.label`, which can be used to display a simple text.
+        But there are also more advanced elements, such as `ui.markdown`, `ui.mermaid` and `ui.html`.
+    ''')
+    def label():
+        ui.label('Hello, world!')
+        ui.markdown('This is **Markdown**.')
+        ui.html('This is <strong>HTML</strong>.')
 
 
 def content() -> None:

website/documentation/tools.py

@@ -65,24 +65,42 @@ def render_docstring(doc: str, with_params: bool = True) -> ui.html:
 
 class text_demo:
 
-    def __init__(self, title: str, explanation: str, tab: Optional[Union[str, Callable]] = None) -> None:
+    def __init__(self, title: str, explanation: str, *,
+                 tab: Optional[Union[str, Callable]] = None,
+                 more_link: Optional[str] = None,
+                 make_menu_entry: bool = True
+                 ) -> None:
         self.title = title
         self.explanation = explanation
-        self.make_menu_entry = True
+        self.make_menu_entry = make_menu_entry
         self.tab = tab
+        self.more_link = more_link
 
     def __call__(self, f: Callable) -> Callable:
-        subheading(self.title, make_menu_entry=self.make_menu_entry)
+        subheading(self.title, make_menu_entry=self.make_menu_entry, more_link=self.more_link)
         ui.markdown(self.explanation).classes('bold-links arrow-links')
         f.tab = self.tab
         return demo(f)
 
 
-class intro_demo(text_demo):
+class section_intro_demo(text_demo):
+
+    def __init__(self, name: str, title: str, explanation: str) -> None:
+        super().__init__(title, explanation, more_link=f'section_{name}', make_menu_entry=False)
+        self.name = name
+        with get_menu():
+            ui.link(title, f'/documentation/section_{name}')
+
+    def __call__(self, f: Callable) -> Callable:
+        result = super().__call__(f)
+        ui.markdown(f'[Read more...](/documentation/section_{self.name})').classes('bold-links arrow-links')
+        return result
+
+
+class main_page_demo(text_demo):
 
     def __init__(self, title: str, explanation: str) -> None:
-        super().__init__(title, explanation)
-        self.make_menu_entry = False
+        super().__init__(title, explanation, make_menu_entry=False)
 
 
 class element_demo: