Merge pull request #1 from litestar-org/flash-1

docs: add plugin docs for flash messages

docs/index.rst

@@ -3,7 +3,7 @@ Litestar library documentation
 
 Litestar is a powerful, flexible, highly performant, and opinionated ASGI framework.
 
-The Litestar framework supports :doc:`/usage/plugins`, ships
+The Litestar framework supports :doc:`/usage/plugins/index`, ships
 with :doc:`dependency injection </usage/dependency-injection>`, :doc:`security primitives </usage/security/index>`,
 :doc:`OpenAPI schema generation </usage/openapi>`, `MessagePack <https://msgpack.org/>`_,
 :doc:`middlewares </usage/middleware/index>`, a great :doc:`CLI </usage/cli>` experience, and much more.

docs/usage/index.rst

@@ -22,7 +22,7 @@ Usage
     metrics/index
     middleware/index
     openapi
-    plugins
+    plugins/index
     responses
     security/index
     static-files

docs/usage/plugins/flash_messages.rst

@@ -0,0 +1,47 @@
+==============
+Flash Messages
+==============
+
+.. todo:: Document flash messages from https://github.com/litestar-org/litestar/pull/3145/
+
+Registering the plugin
+----------------------
+
+.. todo:: Document registering the plugin from
+
+Adding Messages
+---------------
+
+.. todo:: Document adding messages to request scope
+
+Retrieving Messages
+-------------------
+
+.. todo:: Document retrieving messages from request scope
+
+Using Messages in Templates
+---------------------------
+
+.. tab-set::
+
+    .. tab-item:: Jinja2
+
+        .. code-block:: html
+            :caption: Displaying flash messages in a Jinja2 template
+
+            .. todo:: Add Jinja2 example
+
+    .. tab-item:: Mako
+
+        .. code-block:: html
+            :caption: Displaying flash messages in a Mako template
+
+
+            .. todo:: Add Mako example
+
+    .. tab-item:: Mini-Jinja
+
+        .. code-block:: html
+            :caption: Displaying flash messages in a Mini-Jinja template
+
+            .. todo:: Add Mini-Jinja example

docs/usage/plugins.rst → docs/usage/plugins/index.rst

@@ -1,3 +1,4 @@
+=======
 Plugins
 =======
 
@@ -84,7 +85,7 @@ Example
 The following example shows the actual implementation of the ``SerializationPluginProtocol`` for
 `SQLAlchemy <https://www.sqlalchemy.org/>`_ models that is is provided in ``advanced_alchemy``.
 
-.. literalinclude:: ../../litestar/contrib/sqlalchemy/plugins/serialization.py
+.. literalinclude:: ../../../litestar/contrib/sqlalchemy/plugins/serialization.py
    :language: python
    :caption: ``SerializationPluginProtocol`` implementation example
 
@@ -123,3 +124,8 @@ signature (their :func:`__init__` method).
 .. literalinclude:: /examples/plugins/di_plugin.py
    :language: python
    :caption: Dynamically generating signature information for a custom type
+
+.. toctree::
+    :titlesonly:
+
+    flash_messages

docs/usage/requests.rst

@@ -17,7 +17,7 @@ The type of ``data`` an be any supported type, including
 * :class:`TypedDicts <typing.TypedDict>`
 * Pydantic models
 * Arbitrary stdlib types
-* Typed supported via :doc:`plugins </usage/plugins>`
+* Typed supported via :doc:`plugins </usage/plugins/index>`
 
 .. literalinclude:: /examples/request_data/request_data_2.py
     :language: python

litestar/plugins/flash.py

@@ -1,3 +1,4 @@
+"""Plugin for creating and retrieving flash messages."""
 from dataclasses import dataclass
 from typing import Any, Mapping
 
@@ -21,11 +22,22 @@ class FlashPlugin(InitPluginProtocol):
     """Flash messages Plugin."""
 
     def __init__(self, config: FlashConfig):
-        """Initialize the plugin."""
+        """Initialize the plugin.
+
+        Args:
+            config: Configuration for flash messages, including the template engine instance.
+        """
         self.config = config
 
     def on_app_init(self, app_config: AppConfig) -> AppConfig:
-        """Register the message callable on the template engine instance."""
+        """Register the message callable on the template engine instance.
+
+        Args:
+            app_config: The application configuration.
+
+        Returns:
+            The application configuration with the message callable registered.
+        """
         if isinstance(self.config.template_config.engine_instance, MiniJinjaTemplateEngine):
             from litestar.contrib.minijinja import _transform_state
 
@@ -38,12 +50,25 @@ def on_app_init(self, app_config: AppConfig) -> AppConfig:
 
 
 def flash(connection: ASGIConnection, message: str, category: str) -> None:
-    """Add a flash message to the request scope."""
+    """Add a flash message to the request scope.
+
+    Args:
+        connection: The connection instance.
+        message: The message to flash.
+        category: The category of the message.
+    """
     scope_state = ScopeState.from_scope(connection.scope)
     scope_state.flash_messages.append({"message": message, "category": category})
 
 
 def get_flashes(context: Mapping[str, Any]) -> Any:
-    """Get flash messages from the request scope, if any."""
+    """Get flash messages from the request scope, if any.
+
+    Args:
+        context: The context dictionary.
+
+    Returns:
+        The flash messages, if any.
+    """
     scope_state = ScopeState.from_scope(_get_request_from_context(context).scope)
     return scope_state.flash_messages