Introduce a "Map of NiceGUI" (#4128)

This PR adds an overview of the NiceGUI namespace to the documentation
page.

- [x] It's still a draft, because I'm planning to add links to the
individual documentation pages where possible.
- [x] And although I like the blue color to highlight the code snippets,
it can be confused with links. So maybe we find a better way to
highlight them.

---------

Co-authored-by: Rodja Trappe <[email protected]>

Author: falkoschindler

nicegui/ui_run.py

@@ -90,7 +90,7 @@ def run(*,
     :param binding_refresh_interval: time between binding updates (default: `0.1` seconds, bigger is more CPU friendly)
     :param reconnect_timeout: maximum time the server waits for the browser to reconnect (default: 3.0 seconds)
     :param message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable)
-    :param fastapi_docs: enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described `here<https://fastapi.tiangolo.com/tutorial/metadata/>`_, default: `False`)
+    :param fastapi_docs: enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described `here <https://fastapi.tiangolo.com/tutorial/metadata/>`_, default: `False`)
     :param show: automatically open the UI in a browser tab (default: `True`)
     :param on_air: tech preview: `allows temporary remote access <https://nicegui.io/documentation/section_configuration_deployment#nicegui_on_air>`_ if set to `True` (default: disabled)
     :param native: open the UI in a native window of size 800x600 (default: `False`, deactivates `show`, automatically finds an open port)

website/documentation/content/overview.py

@@ -14,6 +14,7 @@
     section_testing,
     section_text_elements,
 )
+from ...style import subheading
 
 doc.title('*NiceGUI* Documentation', 'Reference, Demos and more')
 
@@ -151,3 +152,318 @@ def create_tiles():
             if page.title:
                 ui.label(page.title.replace('*', '')).classes(replace='text-2xl')
             ui.markdown(description).classes(replace='bold-links arrow-links')
+
+
+@doc.ui
+def map_of_nicegui():
+    ui.separator().classes('mt-6')
+    subheading('Map of NiceGUI', anchor_name='map-of-nicegui')
+    ui.add_css('''
+        .map-of-nicegui a code {
+            font-weight: bold;
+        }
+    ''')
+    ui.markdown('''
+        This overview shows the structure of NiceGUI.
+        It is a map of the NiceGUI namespace and its contents.
+        It is not exhaustive, but it gives you a good idea of what is available.
+        An ongoing goal is to make this map more complete and to add missing links to the documentation.
+
+        #### `ui`
+
+        UI elements and other essentials to run a NiceGUI app.
+
+        - [`ui.element`](/documentation/element): base class for all UI elements
+            - customization:
+                - `.props()` and [`.default_props()`](/documentation/element#default_props): add Quasar props and regular HTML attributes
+                - `.classes()` and [`.default_classes()`](/documentation/element#default_classes): add Quasar, Tailwind and custom HTML classes
+                - [`.tailwind`](/documentation/section_styling_appearance#tailwind_css): convenience API for adding Tailwind classes
+                - `.style()` and [`.default_style()`](/documentation/element#default_style): add CSS style definitions
+                - [`.tooltip()`](/documentation/tooltip): add a tooltip to an element
+                - [`.mark()`](/documentation/element_filter#markers): mark an element for querying with an [ElementFilter](/documentation/element_filter)
+            - interaction:
+                - [`.on()`](/documentation/generic_events): add Python and JavaScript event handlers
+                - `.update()`: send an update to the client (mostly done automatically)
+                - `.run_method()`: run a method on the client side
+                - `.get_computed_prop()`: get the value of a property that is computed on the client side
+            - hierarchy:
+                - `with ...:` nesting elements in a declarative way
+                - `__iter__`: an iterator over all child elements
+                - `ancestors`: an iterator over the element's parent, grandparent, etc.
+                - `descendants`: an iterator over all child elements, grandchildren, etc.
+                - `slots`: a dictionary of named slots
+                - `add_slot`: fill a new slot with NiceGUI elements or a scoped slot with template strings
+                - [`clear`](/documentation/section_page_layout#clear_containers): remove all child elements
+                - [`move`](/documentation/element#move_elements): move an element to a new parent
+                - `remove`: remove a child element
+                - `delete`: delete an element and all its children
+                - `is_deleted`: whether an element has been deleted
+        - elements:
+            - [`ui.aggrid`](/documentation/aggrid)
+            - [`ui.audio`](/documentation/audio)
+            - [`ui.avatar`](/documentation/avatar)
+            - [`ui.badge`](/documentation/badge)
+            - [`ui.button`](/documentation/button)
+            - [`ui.button_group`](/documentation/button_group)
+            - [`ui.card`](/documentation/card), `ui.card_actions`, `ui.card_section`
+            - [`ui.carousel`](/documentation/carousel), `ui.carousel_slide`
+            - [`ui.chat_message`](/documentation/chat_message)
+            - [`ui.checkbox`](/documentation/checkbox)
+            - [`ui.chip`](/documentation/chip)
+            - [`ui.circular_progress`](/documentation/circular_progress)
+            - [`ui.code`](/documentation/code)
+            - [`ui.codemirror`](/documentation/codemirror)
+            - [`ui.color_input`](/documentation/color_input)
+            - [`ui.color_picker`](/documentation/color_picker)
+            - [`ui.column`](/documentation/column)
+            - [`ui.context_menu`](/documentation/context_menu)
+            - [`ui.date`](/documentation/date)
+            - [`ui.dialog`](/documentation/dialog)
+            - [`ui.dropdown_button`](/documentation/button_dropdown)
+            - [`ui.echart`](/documentation/echart)
+            - [`ui.editor`](/documentation/editor)
+            - [`ui.expansion`](/documentation/expansion)
+            - [`ui.grid`](/documentation/grid)
+            - [`ui.highchart`](/documentation/highchart)
+            - [`ui.html`](/documentation/html)
+            - [`ui.icon`](/documentation/icon)
+            - [`ui.image`](/documentation/image)
+            - [`ui.input`](/documentation/input)
+            - [`ui.interactive_image`](/documentation/interactive_image)
+            - `ui.item`, `ui.item_label`, `ui.item_section`
+            - [`ui.joystick`](/documentation/joystick)
+            - [`ui.json_editor`](/documentation/json_editor)
+            - [`ui.knob`](/documentation/knob)
+            - [`ui.label`](/documentation/label)
+            - [`ui.leaflet`](/documentation/leaflet)
+            - [`ui.line_plot`](/documentation/line_plot)
+            - [`ui.linear_progress`](/documentation/linear_progress)
+            - [`ui.link`](/documentation/link), `ui.link_target`
+            - [`ui.list`](/documentation/list)
+            - [`ui.log`](/documentation/log)
+            - [`ui.markdown`](/documentation/markdown)
+            - [`ui.matplotlib`](/documentation/matplotlib)
+            - [`ui.menu`](/documentation/menu), `ui.menu_item`
+            - [`ui.mermaid`](/documentation/mermaid)
+            - [`ui.notification`](/documentation/notification)
+            - [`ui.number`](/documentation/number)
+            - [`ui.pagination`](/documentation/pagination)
+            - [`ui.plotly`](/documentation/plotly)
+            - [`ui.pyplot`](/documentation/pyplot)
+            - [`ui.radio`](/documentation/radio)
+            - [`ui.range`](/documentation/range)
+            - [`ui.restructured_text`](/documentation/restructured_text)
+            - [`ui.row`](/documentation/row)
+            - [`ui.scene`](/documentation/scene), [`ui.scene_view`](/documentation/scene#scene_view)
+            - [`ui.scroll_area`](/documentation/scroll_area)
+            - [`ui.select`](/documentation/select)
+            - [`ui.separator`](/documentation/separator)
+            - [`ui.skeleton`](/documentation/skeleton)
+            - [`ui.slider`](/documentation/slider)
+            - [`ui.space`](/documentation/space)
+            - [`ui.spinner`](/documentation/spinner)
+            - [`ui.splitter`](/documentation/splitter)
+            - [`ui.stepper`](/documentation/stepper), `ui.step`, `ui.stepper_navigation`
+            - [`ui.switch`](/documentation/switch)
+            - [`ui.tabs`](/documentation/tabs), `ui.tab`, `ui.tab_panels`, `ui.tab_panel`
+            - [`ui.table`](/documentation/table)
+            - [`ui.textarea`](/documentation/textarea)
+            - [`ui.time`](/documentation/time)
+            - [`ui.timeline`](/documentation/timeline), `ui.timeline_entry`
+            - [`ui.toggle`](/documentation/toggle)
+            - [`ui.tooltip`](/documentation/tooltip)
+            - [`ui.tree`](/documentation/tree)
+            - [`ui.upload`](/documentation/upload)
+            - [`ui.video`](/documentation/video)
+        - special layout [elements](/documentation/page_layout):
+            - `ui.header`
+            - `ui.footer`
+            - `ui.drawer`, `ui.left_drawer`, `ui.right_drawer`
+            - `ui.page_sticky`
+        - special functions and objects:
+            - [`ui.add_body_html`](/documentation/section_pages_routing#add_html_to_the_page) and
+                [`ui.add_head_html`](/documentation/section_pages_routing#add_html_to_the_page): add HTML to the body and head of the page
+            - [`ui.add_css`](/documentation/add_style#add_css_style_definitions_to_the_page),
+                [`ui.add_sass`](/documentation/add_style#add_sass_style_definitions_to_the_page) and
+                [`ui.add_scss`](/documentation/add_style#add_scss_style_definitions_to_the_page): add CSS, SASS and SCSS to the page
+            - [`ui.clipboard`](/documentation/clipboard): interact with the browser's clipboard
+            - [`ui.colors`](/documentation/colors): define the main color theme for a page
+            - `ui.context`: get the current UI context including the `client` and `request` objects
+            - [`ui.dark_mode`](/documentation/dark_mode): get and set the dark mode on a page
+            - [`ui.download`](/documentation/download): download a file to the client
+            - [`ui.keyboard`](/documentation/keyboard): define keyboard event handlers
+            - [`ui.navigate`](/documentation/navigate): let the browser navigate to another location
+            - [`ui.notify`](/documentation/notification): show a notification
+            - [`ui.on`](/documentation/generic_events#custom_events): register an event handler
+            - [`ui.page_title`](/documentation/page_title): change the current page title
+            - [`ui.query`](/documentation/query): query HTML elements on the client side to modify props, classes and style definitions
+            - [`ui.run`](/documentation/run) and `ui.run_with`: run the app (standalone or attached to a FastAPI app)
+            - [`ui.run_javascript`](/documentation/run#run_custom_javascript_on_the_client_side): run custom JavaScript on the client side (can use `getElement()`, `getHtmlElement()`, and `emitEvent()`)
+            - [`ui.teleport`](/documentation/teleport): teleport an element to a different location in the HTML DOM
+            - [`ui.timer`](/documentation/timer): run a function periodically or once after a delay
+            - `ui.update`: send updates of multiple elements to the client
+        - decorators:
+            - [`ui.page`](/documentation/page): define a page (in contrast to the automatically generated "auto-index page")
+            - [`ui.refreshable`](/documentation/refreshable), `ui.refreshable_method`: define refreshable UI containers
+                (can use [`ui.state`](/documentation/refreshable#refreshable_ui_with_reactive_state))
+
+        #### `app`
+
+        App-wide storage, mount points and lifecycle hooks.
+
+        - [`app.storage`](/documentation/storage):
+            - `app.storage.tab`: stored in memory on the server, unique per tab
+            - `app.storage.client`: stored in memory on the server, unique per client connected to a page
+            - `app.storage.user`: stored in a file on the server, unique per browser
+            - `app.storage.general`: stored in a file on the server, shared across the entire app
+            - `app.storage.browser`: stored in the browser's local storage, unique per browser
+        - [lifecycle hooks](/documentation/section_action_events#events):
+            - `app.on_connect()`: called when a client connects
+            - `app.on_disconnect()`: called when a client disconnects
+            - `app.on_startup()`: called when the app starts
+            - `app.on_shutdown()`: called when the app shuts down
+            - `app.on_exception()`: called when an exception occurs
+        - [`app.shutdown()`](/documentation/section_action_events#shut_down_nicegui): shut down the app
+        - static files:
+            - [`app.add_static_files()`](/documentation/section_pages_routing#add_a_directory_of_static_files),
+                `app.add_static_file()`: serve static files
+            - [`app.add_media_files()`](/documentation/section_pages_routing#add_directory_of_media_files),
+                `app.add_media_file()`: serve media files (supports streaming)
+        - [`app.native`](/documentation/section_configuration_deployment#native_mode): configure the app when running in native mode
+
+        #### `html`
+
+        [Pure HTML elements](/documentation/html#other_html_elements):
+
+        `a`,
+        `abbr`,
+        `acronym`,
+        `address`,
+        `area`,
+        `article`,
+        `aside`,
+        `audio`,
+        `b`,
+        `basefont`,
+        `bdi`,
+        `bdo`,
+        `big`,
+        `blockquote`,
+        `br`,
+        `button`,
+        `canvas`,
+        `caption`,
+        `cite`,
+        `code`,
+        `col`,
+        `colgroup`,
+        `data`,
+        `datalist`,
+        `dd`,
+        `del_`,
+        `details`,
+        `dfn`,
+        `dialog`,
+        `div`,
+        `dl`,
+        `dt`,
+        `em`,
+        `embed`,
+        `fieldset`,
+        `figcaption`,
+        `figure`,
+        `footer`,
+        `form`,
+        `h1`,
+        `header`,
+        `hgroup`,
+        `hr`,
+        `i`,
+        `iframe`,
+        `img`,
+        `input_`,
+        `ins`,
+        `kbd`,
+        `label`,
+        `legend`,
+        `li`,
+        `main`,
+        `map_`,
+        `mark`,
+        `menu`,
+        `meter`,
+        `nav`,
+        `object_`,
+        `ol`,
+        `optgroup`,
+        `option`,
+        `output`,
+        `p`,
+        `param`,
+        `picture`,
+        `pre`,
+        `progress`,
+        `q`,
+        `rp`,
+        `rt`,
+        `ruby`,
+        `s`,
+        `samp`,
+        `search`,
+        `section`,
+        `select`,
+        `small`,
+        `source`,
+        `span`,
+        `strong`,
+        `sub`,
+        `summary`,
+        `sup`,
+        `svg`,
+        `table`,
+        `tbody`,
+        `td`,
+        `template`,
+        `textarea`,
+        `tfoot`,
+        `th`,
+        `thead`,
+        `time`,
+        `tr`,
+        `track`,
+        `u`,
+        `ul`,
+        `var`,
+        `video`,
+        `wbr`
+
+        #### `background_tasks`
+
+        Run async functions in the background.
+
+        - `create()`: create a background task
+        - `create_lazy()`: prevent two tasks with the same name from running at the same time
+
+        #### `run`
+
+        Run IO and CPU bound functions in separate threads and processes.
+
+        - [`run.cpu_bound()`](/documentation/section_action_events#running_cpu-bound_tasks): run a CPU-bound function in a separate process
+        - [`run.io_bound()`](/documentation/section_action_events#running_i_o-bound_tasks): run an IO-bound function in a separate thread
+
+        #### `observables`
+
+        Observable collections that notify observers when their contents change.
+
+        - `ObservableCollection`: base class
+        - `ObservableDict`: an observable dictionary
+        - `ObservableList`: an observable list
+        - `ObservableSet`: an observable set
+
+        #### `testing`
+
+        Write automated UI tests which run in a headless browser (slow) or fully simulated in Python (fast).
+
+        - [`Screen`](/documentation/section_testing#screen_fixture) fixture: start a real (headless) browser to interact with your application
+        - [`User`](/documentation/section_testing#user_fixture) fixture: simulate user interaction on a Python level (fast)
+    ''').classes('map-of-nicegui arrow-links bold-links')