Add version information to documentation (#4221)

Inspired by discussion #4137, this PR adds version information to the
documentation in form of comments like
"Added in version 2.1.0"
"Updated in version 2.2.0: ..."
"Since version 2.3.0: ..."

nicegui/app/app.py

@@ -158,7 +158,7 @@ def add_static_files(self,
         :param url_path: string that starts with a slash "/" and identifies the path at which the files should be served
         :param local_directory: local folder with files to serve as static content
         :param follow_symlink: whether to follow symlinks (default: False)
-        :param max_cache_age: value for max-age set in Cache-Control header
+        :param max_cache_age: value for max-age set in Cache-Control header (*added in version 2.8.0*)
         """
         if url_path == '/':
             raise ValueError('''Path cannot be "/", because it would hide NiceGUI's internal "/_nicegui" route.''')
@@ -188,7 +188,7 @@ def add_static_file(self, *,
         :param local_file: local file to serve as static content
         :param url_path: string that starts with a slash "/" and identifies the path at which the file should be served (default: None -> auto-generated URL path)
         :param single_use: whether to remove the route after the file has been downloaded once (default: False)
-        :param max_cache_age: value for max-age set in Cache-Control header
+        :param max_cache_age: value for max-age set in Cache-Control header (*added in version 2.8.0*)
         :return: encoded URL which can be used to access the file
         """
         if max_cache_age < 0:
@@ -279,6 +279,8 @@ def clients(path: str) -> Iterator[Client]:
         When using `@ui.page("/path")` each client gets a private view of this page.
         Updates must be sent to each client individually, which this iterator simplifies.
 
+        *Added in version 2.7.0*
+
         :param path: string to filter clients by
         """
         for client in Client.instances.values():

nicegui/classes.py

@@ -25,7 +25,7 @@ def __call__(self,
 
         :param add: whitespace-delimited string of classes
         :param remove: whitespace-delimited string of classes to remove from the element
-        :param toggle: whitespace-delimited string of classes to toggle
+        :param toggle: whitespace-delimited string of classes to toggle (*added in version 2.7.0*)
         :param replace: whitespace-delimited string of classes to use instead of existing ones
         """
         new_classes = self.update_list(self, add, remove, toggle, replace)

nicegui/client.py

@@ -91,7 +91,10 @@ def is_auto_index_client(self) -> bool:
     @property
     def ip(self) -> Optional[str]:
         """Return the IP address of the client, or None if it is an
-        `auto-index page <https://nicegui.io/documentation/section_pages_routing#auto-index_page>`_."""
+        `auto-index page <https://nicegui.io/documentation/section_pages_routing#auto-index_page>`_.
+
+        *Updated in version 2.0.0: The IP address is available even before the client connects.*
+        """
         return self.request.client.host if self.request is not None and self.request.client is not None else None
 
     @property

nicegui/element.py

@@ -234,7 +234,7 @@ def default_classes(cls,
 
         :param add: whitespace-delimited string of classes
         :param remove: whitespace-delimited string of classes to remove from the element
-        :param toggle: whitespace-delimited string of classes to toggle
+        :param toggle: whitespace-delimited string of classes to toggle (*added in version 2.7.0*)
         :param replace: whitespace-delimited string of classes to use instead of existing ones
         """
         cls._default_classes = Classes.update_list(cls._default_classes, add, remove, toggle, replace)

nicegui/elements/aggrid.py

@@ -101,6 +101,8 @@ def from_polars(cls,
         If the DataFrame contains non-UTF-8 datatypes, they will be converted to strings.
         To use a different conversion, convert the DataFrame manually before passing it to this method.
 
+        *Added in version 2.7.0*
+
         :param df: Polars DataFrame
         :param theme: AG Grid theme (default: 'balham')
         :param auto_size_columns: whether to automatically resize columns to fit the grid width (default: `True`)

nicegui/elements/card.py

@@ -20,6 +20,8 @@ def __init__(self, *,
         the original QCard has no padding by default and hides outer borders and shadows of nested elements.
         If you want the original behavior, use the `tight` method.
 
+        *Updated in version 2.0.0: Don't hide outer borders and shadows of nested elements anymore.*
+
         :param align_items: alignment of the items in the card ("start", "end", "center", "baseline", or "stretch"; default: `None`)
         """
         super().__init__('q-card')

nicegui/elements/colors.py

@@ -28,7 +28,7 @@ def __init__(self, *,
         :param negative: Negative color (default: "#c10015")
         :param info: Info color (default: "#31ccec")
         :param warning: Warning color (default: "#f2c037")
-        :param custom_colors: Custom color definitions for branding (needs ``ui.colors`` to be called before custom color is ever used)
+        :param custom_colors: Custom color definitions for branding (needs ``ui.colors`` to be called before custom color is ever used, *added in version 2.2.0*)
         """
         super().__init__()
         self._props['primary'] = primary

nicegui/elements/echart.py

@@ -37,7 +37,7 @@ def __init__(self,
         :param options: dictionary of EChart options
         :param on_click_point: callback that is invoked when a point is clicked
         :param enable_3d: enforce importing the echarts-gl library
-        :param renderer: renderer to use ("canvas" or "svg")
+        :param renderer: renderer to use ("canvas" or "svg", *added in version 2.7.0*)
         """
         super().__init__()
         self._props['options'] = options

nicegui/elements/json_editor.py

@@ -30,7 +30,7 @@ def __init__(self,
         :param properties: dictionary of JSONEditor properties
         :param on_select: callback which is invoked when some of the content has been selected
         :param on_change: callback which is invoked when the content has changed
-        :param schema: optional `JSON schema <https://json-schema.org/>`_ for validating the data being edited
+        :param schema: optional `JSON schema <https://json-schema.org/>`_ for validating the data being edited (*added in version 2.8.0*)
         """
         super().__init__()
         self._props['properties'] = properties

nicegui/elements/leaflet.py

@@ -36,7 +36,7 @@ def __init__(self,
         :param zoom: initial zoom level of the map (default: 13)
         :param draw_control: whether to show the draw toolbar (default: False)
         :param options: additional options passed to the Leaflet map (default: {})
-        :param hide_drawn_items: whether to hide drawn items on the map (default: False)
+        :param hide_drawn_items: whether to hide drawn items on the map (default: False, *added in version 2.0.0*)
         """
         super().__init__()
         self.add_resource(Path(__file__).parent / 'lib' / 'leaflet')

nicegui/elements/mixins/validation_element.py

@@ -57,6 +57,8 @@ def validate(self, *, return_result: bool = True) -> bool:
         For async validation functions, ``return_result`` must be set to ``False`` and the return value will be ``True``,
         independently of the validation result which is evaluated in the background.
 
+        *Updated in version 2.7.0: Added support for async validation functions.*
+
         :param return_result: whether to return the result of the validation (default: ``True``)
         :return: whether the validation was successful (always ``True`` for async validation functions)
         """

nicegui/elements/query.py

@@ -51,7 +51,7 @@ def classes(self,
 
         :param add: whitespace-delimited string of classes
         :param remove: whitespace-delimited string of classes to remove from the element
-        :param toggle: whitespace-delimited string of classes to toggle
+        :param toggle: whitespace-delimited string of classes to toggle (*added in version 2.7.0*)
         :param replace: whitespace-delimited string of classes to use instead of existing ones
         """
         classes = Classes.update_list(self.element.props['classes'], add, remove, toggle, replace)

nicegui/elements/scene_object3d.py

@@ -203,6 +203,8 @@ def attach(self, parent: Object3D) -> None:
 
         But note that scaling is not preserved.
         If either the parent or the object itself is scaled, the object shape and position can change.
+
+        *Added in version 2.7.0*
         """
         self.detach()
         self.parent = parent
@@ -274,6 +276,8 @@ def detach(self) -> None:
 
         But note that scaling is not preserved.
         If either the parent or the object itself is scaled, the object shape and position can change.
+
+        *Added in version 2.7.0*
         """
         self._move_out_of_parent(self.parent)
         self.parent = self.scene.stack[0]
@@ -330,7 +334,10 @@ def _move_out_of_parent(self, parent: Union[Object3D, SceneObject]) -> None:
 
     @property
     def children(self) -> List[Object3D]:
-        """List of children of the object."""
+        """List of children of the object.
+
+        *Added in version 2.4.0*
+        """
         return [object for object in self.scene.objects.values() if object.parent == self]
 
     def delete(self) -> None:

nicegui/elements/table.py

@@ -45,8 +45,8 @@ def __init__(self,
         A table based on Quasar's `QTable <https://quasar.dev/vue-components/table>`_ component.
 
         :param rows: list of row objects
-        :param columns: list of column objects (defaults to the columns of the first row)
-        :param column_defaults: optional default column properties
+        :param columns: list of column objects (defaults to the columns of the first row *since version 2.0.0*)
+        :param column_defaults: optional default column properties, *added in version 2.0.0*
         :param row_key: name of the column containing unique data identifying the row (default: "id")
         :param title: title of the table
         :param selection: selection type ("single" or "multiple"; default: `None`)
@@ -128,6 +128,8 @@ def from_pandas(cls,
         To use a different conversion, convert the DataFrame manually before passing it to this method.
         See `issue 1698 <https://github.com/zauberzeug/nicegui/issues/1698>`_ for more information.
 
+        *Added in version 2.0.0*
+
         :param df: Pandas DataFrame
         :param columns: list of column objects (defaults to the columns of the dataframe)
         :param column_defaults: optional default column properties
@@ -168,6 +170,8 @@ def from_polars(cls,
         If the DataFrame contains non-UTF-8 datatypes, they will be converted to strings.
         To use a different conversion, convert the DataFrame manually before passing it to this method.
 
+        *Added in version 2.7.0*
+
         :param df: Polars DataFrame
         :param columns: list of column objects (defaults to the columns of the dataframe)
         :param column_defaults: optional default column properties

nicegui/functions/javascript.py

@@ -8,7 +8,7 @@ def run_javascript(code: str, *, timeout: float = 1.0) -> AwaitableResponse:
     This function runs arbitrary JavaScript code on a page that is executed in the browser.
     The client must be connected before this function is called.
     To access a client-side Vue component or HTML element by ID,
-    use the JavaScript functions `getElement()` or `getHtmlElement()`.
+    use the JavaScript functions `getElement()` or `getHtmlElement()` (*added in version 2.9.0*).
 
     If the function is awaited, the result of the JavaScript code is returned.
     Otherwise, the JavaScript code is executed without waiting for a response.

nicegui/functions/navigate.py

@@ -10,6 +10,8 @@ class Navigate:
     """Navigation functions
 
     These functions allow you to navigate within the browser history and to external URLs.
+
+    *Added in version 2.0.0*
     """
 
     def back(self) -> None:

nicegui/functions/style.py

@@ -18,6 +18,8 @@ def add_css(content: Union[str, Path]) -> None:
 
     This function can be used to add CSS style definitions to the head of the HTML page.
 
+    *Added in version 2.0.0*
+
     :param content: CSS content (string or file path)
     """
     if helpers.is_file(content):
@@ -30,6 +32,8 @@ def add_scss(content: Union[str, Path], *, indented: bool = False) -> None:
 
     This function can be used to add SCSS style definitions to the head of the HTML page.
 
+    *Added in version 2.0.0*
+
     :param content: SCSS content (string or file path)
     :param indented: whether the content is indented (SASS) or not (SCSS) (default: `False`)
     """
@@ -46,6 +50,8 @@ def add_sass(content: Union[str, Path]) -> None:
 
     This function can be used to add SASS style definitions to the head of the HTML page.
 
+    *Added in version 2.0.0*
+
     :param content: SASS content (string or file path)
     """
     add_scss(content, indented=True)

nicegui/page_layout.py

@@ -275,7 +275,7 @@ def __init__(self,
         :param position: position on the screen (default: "bottom-right")
         :param x_offset: horizontal offset (default: 0)
         :param y_offset: vertical offset (default: 0)
-        :param expand: whether to fully expand instead of shrinking to fit the content (default: ``False``)
+        :param expand: whether to fully expand instead of shrinking to fit the content (default: ``False``, *added in version 2.1.0*)
         """
         super().__init__('q-page-sticky')
         self._props['position'] = position

nicegui/timer.py

@@ -29,7 +29,7 @@ def __init__(self,
         :param callback: function or coroutine to execute when interval elapses
         :param active: whether the callback should be executed or not (can be changed during runtime)
         :param once: whether the callback is only executed once after a delay specified by `interval` (default: `False`)
-        :param immediate: whether the callback should be executed immediately (default: `True`, ignored if `once` is `True`)
+        :param immediate: whether the callback should be executed immediately (default: `True`, ignored if `once` is `True`, *added in version 2.9.0*)
         """
         super().__init__()
         self.interval = interval

nicegui/ui_run.py

@@ -89,8 +89,8 @@ def run(*,
     :param language: language for Quasar elements (default: `'en-US'`)
     :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 message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable, *added in version 2.9.0*)
+    :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`, *updated in version 2.9.0*)
     :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)

nicegui/ui_run_with.py

@@ -39,7 +39,7 @@ def run_with(
     :param language: language for Quasar elements (default: `'en-US'`)
     :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 message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable, *added in version 2.9.0*)
     :param mount_path: mount NiceGUI at this path (default: `'/'`)
     :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 tailwind: whether to use Tailwind CSS (experimental, default: `True`)

website/documentation/content/aggrid_documentation.py

@@ -130,6 +130,8 @@ def aggrid_from_pandas():
 @doc.demo('Create Grid from Polars DataFrame', '''
     You can create an AG Grid from a Polars DataFrame using the `from_polars` method.
     This method takes a Polars DataFrame as input and returns an AG Grid.
+
+    *Added in version 2.7.0*
 ''')
 def aggrid_from_polars():
     import polars as pl

website/documentation/content/colors_documentation.py

@@ -15,6 +15,8 @@ def main_demo() -> None:
 @doc.demo('Custom colors', '''
     You can add custom color definitions for branding.
     In this case, `ui.colors` must be called before the custom color is ever used.
+
+    *Added in version 2.2.0*
 ''')
 def custom_color_demo() -> None:
     from random import randint

website/documentation/content/html_documentation.py

@@ -21,6 +21,8 @@ def demo_inline() -> None:
 
     Like with any other element, you can add classes, style, props, tooltips and events.
     One convenience is that the keyword arguments are automatically added to the element's `props` dictionary.
+
+    *Added in version 2.5.0*
 ''')
 def other_html_elements():
     from nicegui import html, ui

website/documentation/content/input_documentation.py

@@ -48,6 +48,7 @@ def styling():
     - by passing a callable that returns an error message or `None`, or
     - by passing a dictionary that maps error messages to callables that return `True` if the input is valid.
 
+    *Since version 2.7.0:*
     The callable validation function can also be an async coroutine.
     In this case, the validation is performed asynchronously in the background.
 

website/documentation/content/interactive_image_documentation.py

@@ -66,7 +66,8 @@ def loaded_event():
     You can show crosshairs by passing `cross=True`.
     You can also change the color of the crosshairs by passing a color string.
 
-    Alternatively, you can use the `add_slot` method to add a custom "cross" slot with your own SVG template.
+    *Since version 2.4.0:*
+    You can use the `add_slot` method to add a custom "cross" slot with your own SVG template.
     The `props.x` and `props.y` variables will be available in the template, representing the crosshair position.
 ''')
 def crosshairs():

website/documentation/content/json_editor_documentation.py

@@ -30,6 +30,8 @@ def main_demo() -> None:
     - `id` must be an integer
     - `name` must be a string
     - `price` must be a number greater than 0
+
+    *Added in version 2.8.0*
 ''')
 def schema_demo() -> None:
     schema = {

website/documentation/content/page_documentation.py

@@ -56,6 +56,8 @@ async def wait_for_connection():
     The content on a page is private to the client (the browser tab) and has its own local element context.
     If you want to send updates to _all_ clients of a specific page, you can use the `app.clients` iterator.
     This is useful for modifying UI elements from a background process or from other pages.
+
+    *Added in version 2.7.0*
 ''')
 def multicasting():
     from nicegui import app

website/documentation/content/scene_documentation.py

@@ -273,6 +273,8 @@ def __init__(self, name: str, *, length: float = 1.0) -> None:
     The position and rotation of the object are preserved so that the object does not move in space.
     But note that scaling is not preserved.
     If either the parent or the object itself is scaled, the object shape and position can change.
+
+    *Added in version 2.7.0*
 ''')
 def attach_detach() -> None:
     import math

website/documentation/content/section_text_elements.py

@@ -28,6 +28,8 @@
 
     Like with any other element, you can add classes, style, props, tooltips and events.
     One convenience is that the keyword arguments are automatically added to the element's `props` dictionary.
+
+    *Added in version 2.5.0*
 ''')
 def other_html_elements():
     from nicegui import html, ui