New Doc: docs/userguide/setup-matrix.rst

docs/getting-started/first-steps.rst

@@ -537,7 +537,7 @@ Let's have a quick recap over what we just learned in this section then.
    * - **Configurable Components**
      - Each default component has its ``default_`` fixtures list, which can be used to control or extend the component's functionality.
    * - **Setup Matrix**
-     - The :func:`celery_setup <pytest_celery.fixtures.setup.celery_setup>` will generate a matrix of isolated environments for each test case, based on the enabled components and their configurations.
+     - The :func:`celery_setup <pytest_celery.fixtures.setup.celery_setup>` will generate a :ref:`setup-matrix` of isolated environments for each test case, based on the enabled components and their configurations.
 
 .. _built-in-components:
 

docs/userguide/advanced-installation.rst

@@ -75,5 +75,5 @@ that uses the :ref:`test-setup`.
 
 .. warning::
 
-    The ``all`` extra will install **all** of the vendors dependencies, including the experimental ones,
+    The ``all`` extra will install **all** of the vendors dependencies, including the experimental vendor's dependencies,
     to allow manual configuration of the setup matrix.

docs/userguide/index.rst

@@ -7,10 +7,15 @@
 :Release: |version|
 :Date: |today|
 
+The following sections will enhance your understanding of the pytest-celery plugin and help you to use it effectively.
+It is recommended to first review the :ref:`first-steps` and :ref:`next-steps` sections to get comfortable with the basics
+of the plugin before diving into the advanced features.
+
 .. toctree::
     :maxdepth: 1
 
     advanced-installation
+    setup-matrix
     app-conf
     utils-module
     tasks

docs/userguide/setup-matrix.rst

@@ -0,0 +1,130 @@
+.. _setup-matrix:
+
+===================
+ Test Setup Matrix
+===================
+
+:Release: |version|
+:Date: |today|
+
+The plugin simplifies the setup of test environments by utilizing the
+`pytest fixtures mechanism <https://docs.pytest.org/en/latest/reference/fixtures.html#fixtures>`_ to configure
+each component of the test setup independently which allows for a high degree of flexibility in matching 
+specific Celery architectures to each test case.
+
+In this guide we'll discuss how does the setup matrix work and how to use it.
+
+.. contents::
+    :local:
+    :depth: 2
+
+What is the setup matrix?
+=========================
+
+.. versionadded:: 1.0.0
+
+The setup matrix is a combination of all of the possible Celery architectures that can be used
+with the available :ref:`vendors` for each test. It is automatically generated by the plugin
+to match the installed dependencies when using the default configuration, or it can be manually
+configured to set each test case separately.
+
+The matrix is configured using the :ref:`default-fixtures` of each component and is available
+to the test case using the :ref:`test-setup`.
+
+Common Setups
+=============
+
+.. versionadded:: 1.0.0
+
+The following snippets show how to use the setup matrix to configure manual setups, overriding
+the default configuration using the built-in :ref:`vendors`.
+
+It may be used in conftest.py or in the test file itself.
+
+RabbitMQ Broker and No Backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Use only RabbitMQ as the broker.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_broker_cluster(celery_rabbitmq_broker: RabbitMQTestBroker) -> CeleryBrokerCluster:
+        cluster = CeleryBrokerCluster(celery_rabbitmq_broker)
+        yield cluster
+        cluster.teardown()
+
+2. :ref:`Disable the backend <disable_backend>`.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_backend_cluster():
+        return None
+
+RabbitMQ Broker and Redis Backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Use only RabbitMQ as the broker.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_broker_cluster(celery_rabbitmq_broker: RabbitMQTestBroker) -> CeleryBrokerCluster:
+        cluster = CeleryBrokerCluster(celery_rabbitmq_broker)
+        yield cluster
+        cluster.teardown()
+
+2. Use Redis as the backend.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_backend_cluster(celery_redis_backend: RedisTestBackend) -> CeleryBackendCluster:
+        cluster = CeleryBackendCluster(celery_redis_backend)
+        yield cluster
+        cluster.teardown()
+
+Redis Broker and No Backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Use only Redis as the broker.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_broker_cluster(celery_redis_broker: RedisTestBroker) -> CeleryBrokerCluster:
+        cluster = CeleryBrokerCluster(celery_redis_broker)
+        yield cluster
+        cluster.teardown()
+
+2. :ref:`Disable the backend <disable_backend>`.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_backend_cluster():
+        return None
+
+Redis Broker and Redis Backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Use only Redis as the broker.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_broker_cluster(celery_redis_broker: RedisTestBroker) -> CeleryBrokerCluster:
+        cluster = CeleryBrokerCluster(celery_redis_broker)
+        yield cluster
+        cluster.teardown()
+
+2. Use Redis as the backend.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def celery_backend_cluster(celery_redis_backend: RedisTestBackend) -> CeleryBackendCluster:
+        cluster = CeleryBackendCluster(celery_redis_backend)
+        yield cluster
+        cluster.teardown()