More documentation (#219)

* New Doc: docs/userguide/app-conf.rst

* New Doc: docs/userguide/utils-module.rst

* New Doc: docs/userguide/examples/myutils.rst

* New Doc: docs/userguide/tasks.rst

* New Doc: docs/userguide/signals.rst

* New Doc: docs/faq.rst

* Fixed readthedocs build failure

Author: Nusnus

.readthedocs.yaml

@@ -13,7 +13,7 @@ build:
     post_create_environment:
       # Install poetry
       # https://python-poetry.org/docs/#installing-manually
-      - pip install poetry
+      - pip install poetry==1.7.1
       # Tell poetry to not use a virtual environment
       - poetry config virtualenvs.create false
     post_install:

docs/conf.py

@@ -30,6 +30,7 @@
             r"^http://localhost",
             r"https://github\.com/Jc2k/pytest-docker-tools\?tab=readme-ov-file#images",
             r"https://github\.com/Jc2k/pytest-docker-tools\?tab=readme-ov-file#containers",
+            r"https://github\.com/Jc2k/pytest-docker-tools\?tab=readme-ov-file#fixture-wrappers",
         ],
         autodoc_mock_imports=[],
     )

docs/faq.rst

@@ -7,21 +7,168 @@
 .. contents::
     :local:
 
-.. _faq-general:
+Getting Started
+===============
 
-General
-=======
+What are the prerequisites for installing pytest-celery?
+--------------------------------------------------------
 
-.. _faq-tbd-1:
+**Answer:** The celery package and the required dependencies for the used :ref:`vendors`.
 
-TBD 1?
-------
+How do I install pytest-celery?
+-------------------------------
 
-**Answer:** Yes/No.
+**Answer:** See :ref:`installation`.
 
-.. _faq-tbd-2:
+What initial configuration is required to start using pytest-celery?
+--------------------------------------------------------------------
 
-TBD 2?
-------
+**Answer:** Generally speaking, everything is set up by default. However, you may need to tweak
+some settings to fit your specific use case.
 
-**Answer:** Yes/No.
+For new projects, it is recommended to at least start with a ``pytest.ini`` file at the root of your project
+with the following content:
+
+.. code-block:: ini
+
+    [pytest]
+    log_cli = true
+    log_cli_level = INFO
+    log_cli_format = %(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)
+    log_cli_date_format = %Y-%m-%d %H:%M:%S
+
+This will enable plugin logging to the console, which can be helpful for debugging.
+
+Are there any example projects or templates to help me get started?
+-------------------------------------------------------------------
+
+**Answer:** Yes. See the :ref:`examples` section.
+
+In addition, you may review the `official Celery smoke tests <https://github.com/celery/celery/tree/main/t/smoke>`_
+which are the defacto production environment for the plugin.
+
+Configuration and Customization
+===============================
+
+Can I use pytest-celery with different message brokers or backends?
+-------------------------------------------------------------------
+
+**Answer:** Yes. The built-in :ref:`vendors` are supported out of the box, but you can also use custom ones,
+or reconfigure the built-in ones to fit your needs.
+
+Vendors are different technologies that provides components to the environment.
+Such components may be brokers, backends or worker components, which are constructed by a node controller
+and a docker container combination.
+
+If you provide your own component (broker/backend/worker) using your own docker image, you may inject
+the component into the environment as described in the :ref:`architecture-injection` section.
+
+How can I manage worker concurrency settings in pytest-celery?
+--------------------------------------------------------------
+
+**Answer:** Using the :func:`default_worker_app <pytest_celery.vendors.worker.fixtures.default_worker_app>` fixture.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def default_worker_app(default_worker_app: Celery) -> Celery:
+        app = default_worker_app
+        app.conf.worker_concurrency = 42
+        return app
+
+For more details, see :ref:`worker-app-configuration`.
+
+How do I simulate different environments using pytest-celery?
+-------------------------------------------------------------
+
+**Answer:** See :ref:`manipulating-the-environment`.
+
+Debugging and Troubleshooting
+=============================
+
+Why doesn't the worker recognize my tasks?
+------------------------------------------
+
+**Answer:** Because you don't use the :func:`default_worker_tasks <pytest_celery.vendors.worker.fixtures.default_worker_tasks>` fixture.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def default_worker_tasks(default_worker_tasks: set) -> set:
+        from tests import tasks
+
+        default_worker_tasks.add(tasks)
+        return default_worker_tasks
+
+For more details, see :ref:`injecting-tasks`.
+
+Why aren't my consumer signal handlers triggering?
+--------------------------------------------------
+
+**Answer:** Because you don't use the :func:`default_worker_signals <pytest_celery.vendors.worker.fixtures.default_worker_signals>` fixture.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def default_worker_signals(default_worker_signals: set) -> set:
+        from tests import signals
+
+        default_worker_signals.add(signals)
+        yield default_worker_signals
+
+For more details, see :ref:`injecting-signals-handlers`.
+
+What should I do if the Celery worker doesn't start?
+----------------------------------------------------
+
+**Answer:** This is most probably due to docker build failure.
+
+1. Try to build your worker image manually to see if there are any errors. Make sure to use the same arguments as the plugin.
+2. If it does, then it is probably due to incorrect setup configuration. Review your fixtures usage.
+
+How can I manually inspect my running setup during a test execution?
+--------------------------------------------------------------------
+
+**Answer:** You may place a breakpoint in your test and inspect the environment using any standard tool.
+
+If possible, the `Docker Desktop <https://www.docker.com/products/docker-desktop/>`_ is very helpful for inspecting
+the running containers during the test execution.
+
+Integrating with Docker
+=======================
+
+How do I get pytest-celery to work with Docker?
+-----------------------------------------------
+
+**Answer:** The engine behind the plugin's docker integration is :pypi:`pytest-docker-tools`.
+
+It does not interact with Docker directly.
+
+The Docker environment should be install normally, regardless of the plugin.
+
+How can I clean up Docker artifacts left after a test run?
+----------------------------------------------------------
+
+**Answer:** You may use this snippet from the ``tox -e clean`` environment.
+
+.. literalinclude:: ../tox.ini
+   :language: ini
+   :caption: tox.ini
+   :start-after: make -C ./docs clean
+   :end-before: [testenv:docs]
+
+What are the common pitfalls when integrating pytest-celery with Docker, and how can I avoid them?
+--------------------------------------------------------------------------------------------------
+
+**Answer:** The most common issues encountered so far are limited docker resources and network issues.
+
+To avoid these, you may:
+
+1. Increase the resources available to Docker.
+2. Use the :pypi:`pytest-rerunfailures` pytest plugin to retry failed tests with:
+
+.. code-block:: bash
+
+    --reruns 5 --reruns-delay 60 --rerun-except AssertionError
+
+Experiment with the values to find the best fit for your environment.

docs/getting-started/first-steps.rst

@@ -340,6 +340,8 @@ Before we can learn how to fit the environment to our needs, let's have a quick
    * - **Isoalted Environments**
      - Each test case has its own instances of the environment, allowing for parallelism and isolation of test cases.
 
+.. _manipulating-the-environment:
+
 Manipulating the Environment
 ============================
 
@@ -763,7 +765,7 @@ Tasks
 -----
 
 This will be our ``tasks.py`` file. It adds a simple ``noop`` task
-`Using the @shared_task decorator <https://docs.celeryq.dev/en/main/django/first-steps-with-django.html#using-the-shared-task-decorator>`_.
+`Using the @shared_task decorator <https://docs.celeryq.dev/en/stable/django/first-steps-with-django.html#using-the-shared-task-decorator>`_.
 
 .. code-block:: python
 

docs/getting-started/next-steps.rst

@@ -154,8 +154,8 @@ For example, such ``signals.py`` module might look like this:
 Celery app
 ~~~~~~~~~~
 
-The provided :ref:`app.py <content-app>` uses the `config_from_object() <https://docs.celeryq.dev/en/main/userguide/application.html#config-from-object>`_
-and `app.conf.changes <https://docs.celeryq.dev/en/main/userguide/application.html#configuration>`_ to transmit the configuration
+The provided :ref:`app.py <content-app>` uses the `config_from_object() <https://docs.celeryq.dev/en/stable/userguide/application.html#config-from-object>`_
+and `app.conf.changes <https://docs.celeryq.dev/en/stable/userguide/application.html#configuration>`_ to transmit the configuration
 from the test environment to the worker container.
 
 The ``app.conf`` is set like this when the worker is booting up: