More documentation (#229)

* Added references to setup-matrix in appropriate places

* Added advanced-installation-section reference

* New Doc: Vendor Class

Author: Nusnus

docs/getting-started/introduction.rst

@@ -260,4 +260,4 @@ Quick Jump
 
 .. tip::
 
-    See :ref:`advanced-installation` for more advanced installation options.
+    See :ref:`advanced-installation-section` for more advanced installation options.

docs/getting-started/vendors.rst

@@ -42,7 +42,7 @@ Backends
 Experimental brokers may be functional but are not confirmed to be
 production ready.
 
-Enabled means that it is automatically added to the test setup matrix
+Enabled means that it is automatically added to the test :ref:`setup-matrix`
 when running the test suite :ref:`if the vendor dependencies are installed <installation>`.
 
 .. warning::
@@ -67,6 +67,8 @@ The Dockerfile is published with the source code and can be found using
    :language: docker
    :caption: pytest_celery.vendors.worker.Dockerfile
 
+.. _custom-vendors:
+
 Custom Vendors
 ==============
 
@@ -103,3 +105,124 @@ Custom Worker
     :show-inheritance:
     :inherited-members:
     :no-index:
+
+.. _vendor-class:
+
+Vendor Class
+============
+
+The **Vendor Class** is an optional mechanism for OOP style configuration of the plugin's vendors.
+It allows registering a class that defines how does the vendor behave and configured.
+
+The vendor class represents the vendor's container class that is used automatically by the plugin.
+
+The following diagram shows the relationship between the vendor class and the vendor's infrastructure.
+
+.. mermaid::
+
+    graph TD;
+        Vendor[Vendor] --> BrokerComponent[Broker Component]
+        Vendor --> BackendComponent[Backend Component]
+        Vendor --> WorkerComponent[Worker Component]
+
+        BrokerComponent --> Comp
+        BackendComponent --> Comp
+        WorkerComponent --> Comp
+
+        subgraph Comp["Component"]
+            Node[Node] --> Container[Container]
+        end
+
+        Comp --> DefaultFixtures[Default Fixtures]
+        Comp --> VendorClass[Vendor Class]
+        VendorClass -. "You are here" .-> VendorClass
+        DefaultFixtures <.-> VendorClass
+
+        style Vendor fill:#f9f,stroke:#333,stroke-width:4px
+        style Comp fill:#ddf,stroke:#333,stroke-width:2px
+        style Node fill:#eeffdd,stroke:#333
+        style Container fill:#ffffee,stroke:#333
+        style VendorClass fill:#ffeedd,stroke:#333
+
+Use Cases
+~~~~~~~~~
+
+.. warning::
+
+    It is used only to override the built-in vendors **containers**.
+
+Registering a Vendor Class
+--------------------------
+
+The plugin uses the vendor class to implement the default fixtures of the vendor.
+To override it, create your own vendor class and subclass the matching built-in vendor class
+to include the built-in fixtures implementation.
+
+Worker Example
+##############
+
+.. code-block:: python
+
+    class MyWorkerContainer(CeleryWorkerContainer):
+        @property
+        def client(self) -> Any:
+            return self
+
+        @classmethod
+        def version(cls) -> str:
+            return celery.__version__
+
+        @classmethod
+        def log_level(cls) -> str:
+            return "INFO"
+
+        @classmethod
+        def worker_name(cls) -> str:
+            return "my_tests_worker"
+
+        @classmethod
+        def worker_queue(cls) -> str:
+            return "my_tests_queue"
+
+        def post_initialization_logic(self) -> None:
+            pass
+
+And then, register it using the matching default fixture.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def default_worker_container_cls() -> Type[CeleryWorkerContainer]:
+        return MyWorkerContainer
+
+.. warning::
+
+    The worker vendor requires another fixture to be registered to allow configuring the worker
+    before it gets built.
+
+.. code-block:: python
+
+    @pytest.fixture(scope="session")
+    def default_worker_container_session_cls() -> Type[CeleryWorkerContainer]:
+        return MyWorkerContainer
+
+There's no ``session`` vendor class for other vendors.
+
+- For RabbitMQ Broker use :func:`default_rabbitmq_broker_cls <pytest_celery.vendors.rabbitmq.fixtures.default_rabbitmq_broker_cls>`.
+- For Redis Broker use :func:`default_redis_broker_cls <pytest_celery.vendors.redis.broker.fixtures.default_redis_broker_cls>`.
+- For Redis Backend use :func:`default_redis_backend_cls <pytest_celery.vendors.redis.backend.fixtures.default_redis_backend_cls>`.
+- For Memcache Backend use :func:`default_memcached_backend_cls <pytest_celery.vendors.memcached.fixtures.default_memcached_backend_cls>`.
+
+Accessing the Vendor Class
+--------------------------
+
+Once a vendor class has been registered, it can be accessed using the :ref:`test-setup`.
+Any additional API added to the class can be accessed as well.
+
+For example,
+
+.. code-block:: python
+
+    def test_accessing_post_initialization_logic(celery_setup: CeleryTestSetup):
+        worker: MyWorkerContainer = celery_setup.worker
+        worker.post_initialization_logic()

docs/includes/installation.txt

@@ -29,7 +29,7 @@ the plugin will allow extending the default configurations, up to the supported
 .. warning::
 
     If you don't install any vendor (e.g. no extras and no manual installation), the plugin will result in an
-    empty setup matrix and might not be fully functional.
+    empty :ref:`setup-matrix` and might not be fully functional.
 
 To install the vendors, you may either install all of the dependencies manually, or use the following extras:
 

docs/userguide/advanced-installation.rst

@@ -7,7 +7,7 @@
 :Release: |version|
 :Date: |today|
 
-The pytest-celery plugin uses the environment dependencies to install and configure the default setup matrix.
+The pytest-celery plugin uses the environment dependencies to install and configure the default :ref:`setup-matrix`.
 The available dependencies are the feature flags for the available :ref:`vendors`.
 
 This guide will explain how to install the plugin, how to use the dependencies feature flags and how to
@@ -21,6 +21,8 @@ We will start by reviewing the standard installation instructions.
 
 .. include:: ../includes/installation.txt
 
+.. _advanced-installation-section:
+
 Advanced Installation
 =====================