diff --git a/docs/index.rst b/docs/index.rst
index be01d21e10..92953eec9b 100644
--- a/docs/index.rst
+++ b/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 `, :doc:`security primitives `,
:doc:`OpenAPI schema generation `, `MessagePack `_,
:doc:`middlewares `, a great :doc:`CLI ` experience, and much more.
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
index 632375c475..b19abc4ca4 100644
--- a/docs/usage/index.rst
+++ b/docs/usage/index.rst
@@ -22,7 +22,7 @@ Usage
metrics/index
middleware/index
openapi
- plugins
+ plugins/index
responses
security/index
static-files
diff --git a/docs/usage/plugins/flash_messages.rst b/docs/usage/plugins/flash_messages.rst
new file mode 100644
index 0000000000..720a838e5b
--- /dev/null
+++ b/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
diff --git a/docs/usage/plugins.rst b/docs/usage/plugins/index.rst
similarity index 97%
rename from docs/usage/plugins.rst
rename to docs/usage/plugins/index.rst
index 4911b8da23..ff0cdc1652 100644
--- a/docs/usage/plugins.rst
+++ b/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 `_ 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
diff --git a/docs/usage/requests.rst b/docs/usage/requests.rst
index fdc65f2784..485748ac8c 100644
--- a/docs/usage/requests.rst
+++ b/docs/usage/requests.rst
@@ -17,7 +17,7 @@ The type of ``data`` an be any supported type, including
* :class:`TypedDicts `
* Pydantic models
* Arbitrary stdlib types
-* Typed supported via :doc:`plugins `
+* Typed supported via :doc:`plugins `
.. literalinclude:: /examples/request_data/request_data_2.py
:language: python
diff --git a/litestar/plugins/flash.py b/litestar/plugins/flash.py
index ff472b8077..6b61040120 100644
--- a/litestar/plugins/flash.py
+++ b/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