Repository: airtai/faststream
Pull request #2103: Added pros and cons to publishers page
Author: login: ghost
Labels: name: documentation
description: Improvements or additions to documentation
Created: 2025-03-10T23:58:26Z | Merged: 2025-03-17T16:23:28Z

# Added pros and cons to publishers page

## MD Changes

- Added pros and cons to "Decorator" page 
- Added pros and cons to "Broker Publish" page 
- Added pros and cons to "Direct Publishing" page 
- Added pros and cons to "Object Decorator" page 

## Other Changes
- Added ```material-icons``` configuration to ```mkdocs.yml``` file for ```material-icons``` support
- Added ```css``` styles for marks

## New features
- New exclamation mark
- New checked mark
- New X mark

## Images

*Broker publish*
![brokerpublish](https://github.com/user-attachments/assets/bc1ca99e-4b3e-450e-aec8-e671b773b5cf)
*Decorator*
![decorator](https://github.com/user-attachments/assets/6ee5f8e6-0603-4fa6-8774-2c23f1c95ca6)
*Object Decorator*
![objectdecorator](https://github.com/user-attachments/assets/59a9fda6-0338-4c69-9667-5fdb55fdb460)
*Direct Publishing*
![directpublishing](https://github.com/user-attachments/assets/080c493e-2f97-4f6e-bf9f-fa340ffe9c30)






Diff:
diff --git a/docs/docs/en/getting-started/publishing/broker.md b/docs/docs/en/getting-started/publishing/broker.md
index 03c83a479a..7b3ff900c3 100644
--- a/docs/docs/en/getting-started/publishing/broker.md
+++ b/docs/docs/en/getting-started/publishing/broker.md
@@ -14,6 +14,17 @@ The easiest way to publish a message is to use a Broker, which allows you to use
 
 In the **FastStream** project, this call is not represented in the **AsyncAPI** scheme. You can use it to send rarely-publishing messages, such as startup or shutdown events.
 
+!!! tip "Pros and Cons"
+
+    :material-checkbox-marked:{.checked_mark} **Easy to use** - Publishing messages in **FastStream** is intuitive and requires minimal effort.
+
+    :material-checkbox-marked:{.checked_mark} **Broker availability from Context** - You can leverage **FastStream's** [```Context```](../context/index.md#section{.css-styles}), a built-in Dependency Injection (DI) container, to work with brokers or other external services.
+
+    :fontawesome-solid-square-xmark:{.x_mark} **No AsyncAPI support** - [```AsyncAPI```](../asyncapi/export.md#section{.css-styles}) is a specification for describing asynchronous APIs used in messaging applications. This method currently does not support this standard.
+
+    :fontawesome-solid-square-xmark:{.x_mark} **No testing support** - This method lacks full [```Testing```](./test.md#section{.css-styles}) support.
+
+
 === "AIOKafka"
     ```python linenums="1" hl_lines="10 20"
     {!> docs_src/getting_started/publishing/kafka/broker.py !}
diff --git a/docs/docs/en/getting-started/publishing/decorator.md b/docs/docs/en/getting-started/publishing/decorator.md
index 57ed3ddbff..98e2ead988 100644
--- a/docs/docs/en/getting-started/publishing/decorator.md
+++ b/docs/docs/en/getting-started/publishing/decorator.md
@@ -17,6 +17,20 @@ It creates a structured DataPipeline unit with an input and output. The order of
 !!! note
     It uses the handler function's return type annotation to cast the function's return value before sending, so be accurate with it.
 
+!!! tip "Pros and Cons"
+
+    :material-checkbox-marked:{.checked_mark} **Easy to use** - Publishing messages in **FastStream** is intuitive and requires minimal effort.
+
+    :material-checkbox-marked:{.checked_mark} **AsyncAPI support** - [```AsyncAPI```](../asyncapi/export.md#section{.css-styles}) is a specification for describing asynchronous APIs used in messaging applications. This method currently does not support this standard.
+
+    :fontawesome-solid-square-xmark:{.x_mark} **No testing support** - This method lacks full [```Testing```](./test.md#section{.css-styles}) support.
+
+    :fontawesome-solid-square-xmark:{.x_mark} **No broker availability from Context** - You cannot leverage **FastStream's** [```Context```](../context/index.md#section{.css-styles}), a built-in Dependency Injection (DI) container, to work with brokers or other external services.
+
+    :fontawesome-solid-square-xmark:{.x_mark} **Not reusable** - This method cannot be reused.
+
+    :fontawesome-solid-triangle-exclamation:{.warning_mark} The message will **always** be published.
+
 === "AIOKafka"
     ```python linenums="1" hl_lines="9"
     {!> docs_src/getting_started/publishing/kafka/decorator.py !}
diff --git a/docs/docs/en/getting-started/publishing/direct.md b/docs/docs/en/getting-started/publishing/direct.md
index 8cf7b5bc66..2a26e2a21d 100644
--- a/docs/docs/en/getting-started/publishing/direct.md
+++ b/docs/docs/en/getting-started/publishing/direct.md
@@ -14,6 +14,18 @@ The Publisher Object provides a full-featured way to publish messages. It has an
 
 This method creates a reusable Publisher object that can be used directly to publish a message:
 
+!!! tip "Pros and Cons"
+
+    :material-checkbox-marked:{.checked_mark} **AsyncAPI support** - [**```AsyncAPI```**](../asyncapi/export.md#section{.css-styles}) is a specification for describing asynchronous APIs used in messaging applications. This method currently does not support this standard.
+
+    :material-checkbox-marked:{.checked_mark} **Testing support** - This method has full [**```Testing```**](./test.md#section{.css-styles}) support.
+
+    :material-checkbox-marked:{.checked_mark} **Broker availability from Context** - You can leverage **FastStream's** [**```Context```**](../context/index.md#section{.css-styles}), a built-in Dependency Injection (DI) container, to work with brokers or other external services.
+
+    :material-checkbox-marked:{.checked_mark} **Optional publication** - You can create optional publications.
+
+    :material-checkbox-marked:{.checked_mark} **Reusable** - This method is reusable.
+
 === "AIOKafka"
     ```python linenums="1" hl_lines="7 11"
     {!> docs_src/getting_started/publishing/kafka/direct.py !}
diff --git a/docs/docs/en/getting-started/publishing/object.md b/docs/docs/en/getting-started/publishing/object.md
index 1ddd59bae0..77afffd2b2 100644
--- a/docs/docs/en/getting-started/publishing/object.md
+++ b/docs/docs/en/getting-started/publishing/object.md
@@ -17,6 +17,18 @@ Additionally, this object can be used as a decorator. The order of Subscriber an
 !!! note
     It uses the handler function's return type annotation to cast the function's return value before sending, so be accurate with it.
 
+!!! tip "Pros and Cons"
+
+    :material-checkbox-marked:{.checked_mark} **AsyncAPI support** - [**```AsyncAPI```**](../asyncapi/export.md#section{.css-styles}) is a specification for describing asynchronous APIs used in messaging applications. This method supports this standard.
+
+    :material-checkbox-marked:{.checked_mark} **Testing support** - This method has full [**```Testing```**](./test.md#section{.css-styles}) support.
+
+    :material-checkbox-marked:{.checked_mark} **Broker availability from Context** - You can leverage **FastStream's** [**```Context```**](../context/index.md#section{.css-styles}), a built-in Dependency Injection (DI) container, to work with brokers or other external services.
+
+    :material-checkbox-marked:{.checked_mark} **Reusable** - This method is reusable.
+
+    :fontawesome-solid-triangle-exclamation:{.warning_mark} The message will **always** be published.
+
 === "AIOKafka"
     ```python linenums="1" hl_lines="7 9"
     {!> docs_src/getting_started/publishing/kafka/object.py !}
diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css
index 5023c11b7b..7d5f3c756e 100644
--- a/docs/docs/stylesheets/extra.css
+++ b/docs/docs/stylesheets/extra.css
@@ -86,6 +86,18 @@ a.internal-link::after {
     content: "\00A0↪";
 }
 
+.checked_mark {
+    color: #30af00;
+}
+
+.x_mark {
+    color: #ce242d;
+}
+
+.warning_mark {
+    color: #d19d00;
+}
+
 #gurubase-page-content-wrapper {
     display: flex;
     flex-direction: column;
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 5dd213d1df..d1fde2000c 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -156,6 +156,9 @@ markdown_extensions:
       alternate_style: true      # create tabs group
   - attr_list                    # specify html attrs in markdown
   - md_in_html                   # render md wrapped to html tags
+  - pymdownx.emoji:              # render material icons
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 extra:
   analytics:


Reviews:
user: login: Lancetnik
body: Please, add links to according docs sections
state: CHANGES_REQUESTED
author_association: MEMBER
submitted_at: 2025-03-11T19:53:02Z
user: login: Lancetnik
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-17T16:13:30Z

Review comments:
diff_hunk: @@ -17,6 +17,22 @@ It creates a structured DataPipeline unit with an input and output. The order of
 !!! note
     It uses the handler function's return type annotation to cast the function's return value before sending, so be accurate with it.
 
+---
+
+:material-checkbox-marked:{.checked_mark} Easy to use
+
+:material-checkbox-marked:{.checked_mark} Availability from ```Context```
path: docs/docs/en/getting-started/publishing/decorator.md
user: login: Lancetnik
body: Not available
created_at: 2025-03-11T19:47:16Z
author_association: MEMBER
diff_hunk: @@ -17,6 +17,22 @@ It creates a structured DataPipeline unit with an input and output. The order of
 !!! note
     It uses the handler function's return type annotation to cast the function's return value before sending, so be accurate with it.
 
+---
+
+:material-checkbox-marked:{.checked_mark} Easy to use
+
+:material-checkbox-marked:{.checked_mark} Availability from ```Context```
+
+:fontawesome-solid-square-xmark:{.x_mark} ```AsyncAPI``` support
path: docs/docs/en/getting-started/publishing/decorator.md
user: login: Lancetnik
body: Available
created_at: 2025-03-11T19:49:41Z
author_association: MEMBER
diff_hunk: @@ -14,6 +14,24 @@ The Publisher Object provides a full-featured way to publish messages. It has an
 
 This method creates a reusable Publisher object that can be used directly to publish a message:
 
+---
+
+:material-checkbox-marked:{.checked_mark} Availability from ```Context```
+
+:material-checkbox-marked:{.checked_mark} ```AsyncAPI``` support
+
+:material-checkbox-marked:{.checked_mark} Testing support
+
+:material-checkbox-marked:{.checked_mark} Optional publication
+
+:material-checkbox-marked:{.checked_mark} Can be reused
+
+:fontawesome-solid-triangle-exclamation:{.warning_mark} Most verbose way
+
+:fontawesome-solid-triangle-exclamation:{.warning_mark} The message will **always** be published
path: docs/docs/en/getting-started/publishing/direct.md
user: login: Lancetnik
body: It conflicts with "optional publishing" – remove
created_at: 2025-03-11T19:51:55Z
author_association: MEMBER

PR comments:
user: login: ghost
created_at: 2025-03-11T20:28:23Z
body: Okay! I'll do that as soon as i can 
author_association: NONE
user: login: Lancetnik
created_at: 2025-03-15T12:08:08Z
body: @kumaranvpl – I need your help here. Can you review this one, please?
author_association: MEMBER
user: login: kumaranvpl
created_at: 2025-03-15T14:06:04Z
body: @Lancetnik I will check it out tomorrow. 
author_association: CONTRIBUTOR
user: login: kumaranvpl
created_at: 2025-03-17T06:13:48Z
body: @Lancetnik Proofread documentation and resolved merge conflicts. Review and merge when you are free please.
author_association: CONTRIBUTOR