Documentation Enhancement (#192)

* Added module docstring to src/pytest_celery/api/*

* Added module docstring to src/pytest_celery/fixtures/*

* Added module docstring to src/pytest_celery/vendors/*

* Enhacned docs/glossary.rst

Author: Nusnus

docs/getting-started/first-steps.rst

@@ -800,8 +800,8 @@ Next, we'll configure a single backend setup using the built-in Redis backend, i
 .. code-block:: python
 
     @pytest.fixture
-    def celery_backend_cluster(celery_redis_broker: RedisTestBroker) -> CeleryBrokerCluster:
-        cluster = CeleryBrokerCluster(celery_redis_broker)
+    def celery_backend_cluster(celery_redis_backend: RedisTestBackend) -> CeleryBackendCluster:
+        cluster = CeleryBackendCluster(celery_redis_backend)
         yield cluster
         cluster.teardown()
 
@@ -837,7 +837,7 @@ In our test case, we'll assert our setup is configured as expected, and publish
 
     def test_hello_world(celery_setup: CeleryTestSetup):
         assert isinstance(celery_setup.broker, RabbitMQTestBroker)
-        assert isinstance(celery_setup.backend, RedisTestBroker)
+        assert isinstance(celery_setup.backend, RedisTestBackend)
         assert noop.s().apply_async().get() is None
 
 test_helloworld.py

docs/glossary.rst

@@ -9,6 +9,19 @@ Glossary
     tbd
         To be defined.
 
+    container
+        A container in the context of pytest-celery is a low level implementation of a Celery architecture
+        component.
+
+    node
+        A node in the context of pytest-celery is a high level implementation of a Celery architecture
+        component.
+
+    component
+        Celery architecture component that is defined using a container, a node, APIs & pytest fixtures.
+        It is a collective name for all of the parts that compose a component, according to the pytest-celery
+        design.
+
     vendor
-        A Celery-related technology provider. This can refer to the
-        built-in components, or third-party extensions.
+        Independent built-in components provided by the plugin. Vendors can be used as-is,
+        reconfigured, extended or overridden completely by the user.

poetry.lock

@@ -1,3 +1,9 @@
+"""Backend components represents Celery's result backend instances.
+
+This module provides the base API for creating new backend components by
+defining the base classes for backend nodes and clusters.
+"""
+
 from __future__ import annotations
 
 from pytest_celery.api.base import CeleryTestCluster
@@ -15,6 +21,7 @@ class CeleryTestBackend(CeleryTestNode):
 
     @classmethod
     def default_config(cls) -> dict:
+        """Default node configurations if not overridden by the user."""
         return {
             "url": DEFAULT_WORKER_ENV["CELERY_RESULT_BACKEND"],
             "host_url": DEFAULT_WORKER_ENV["CELERY_RESULT_BACKEND"],
@@ -40,6 +47,7 @@ class CeleryBackendCluster(CeleryTestCluster):
 
     @classmethod
     def default_config(cls) -> dict:
+        """Default cluster configurations if not overridden by the user."""
         return {
             "urls": [DEFAULT_WORKER_ENV["CELERY_RESULT_BACKEND"]],
             "host_urls": [DEFAULT_WORKER_ENV["CELERY_RESULT_BACKEND"]],

src/pytest_celery/api/backend.py

@@ -1,3 +1,11 @@
+"""The node/cluster set are designed to provide a common interface for
+encapsulating the implementation of test components and their integration with
+the test framework.
+
+This module provides the base API for creating new components by
+defining the base classes for nodes and clusters.
+"""
+
 from __future__ import annotations
 
 from abc import abstractmethod

src/pytest_celery/api/base.py

@@ -1,3 +1,9 @@
+"""Broker components represents Celery's broker instances.
+
+This module provides the base API for creating new broker components by
+defining the base classes for broker nodes and clusters.
+"""
+
 from __future__ import annotations
 
 from pytest_celery.api.base import CeleryTestCluster
@@ -15,6 +21,7 @@ class CeleryTestBroker(CeleryTestNode):
 
     @classmethod
     def default_config(cls) -> dict:
+        """Default node configurations if not overridden by the user."""
         return {
             "url": DEFAULT_WORKER_ENV["CELERY_BROKER_URL"],
             "host_url": DEFAULT_WORKER_ENV["CELERY_BROKER_URL"],
@@ -40,6 +47,7 @@ class CeleryBrokerCluster(CeleryTestCluster):
 
     @classmethod
     def default_config(cls) -> dict:
+        """Default cluster configurations if not overridden by the user."""
         return {
             "urls": [DEFAULT_WORKER_ENV["CELERY_BROKER_URL"]],
             "host_urls": [DEFAULT_WORKER_ENV["CELERY_BROKER_URL"]],

src/pytest_celery/api/broker.py

@@ -1,3 +1,10 @@
+"""The ``pytest_docker_tools`` package powers the Docker container management
+for the plugin.
+
+This module extends the ``Container`` class from the package to provide
+the base API for creating new test containers in a Celery test environment.
+"""
+
 from __future__ import annotations
 
 from typing import Any

src/pytest_celery/api/container.py

@@ -1,3 +1,9 @@
+"""The test setup represents the main entry point for accessing the celery
+architecture from the test.
+
+This module provides the base API for creating new test setups.
+"""
+
 from __future__ import annotations
 
 from celery import Celery

src/pytest_celery/api/setup.py

@@ -1,3 +1,9 @@
+"""Worker components represents Celery's worker instances.
+
+This module provides the base API for creating new worker components by
+defining the base classes for worker nodes and clusters.
+"""
+
 from __future__ import annotations
 
 import json

src/pytest_celery/api/worker.py

@@ -1,3 +1,14 @@
+"""Every backend component is added to the test matrix using the fixtures of
+this module.
+
+These fixtures will configure the test setup for all supported celery
+backends by default. Every backend will be executed as a separate test
+case, and the test will be executed for each supported celery backend.
+
+You may override these fixtures to customize the test setup for your
+specific needs.
+"""
+
 # mypy: disable-error-code="misc"
 
 from __future__ import annotations