Documentation Engine Enhancements

.github/workflows/linter.yml

@@ -3,27 +3,19 @@ name: Linter
 on: [pull_request]
 
 jobs:
-  linter:
+  check:
+    name: ${{ matrix.check }} check
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        check: [lint, mypy]
     steps:
-
-      - name: Checkout branch
-        uses: actions/checkout@v4
-
-      - name: Run pre-commit
-        uses: pre-commit/action@v3.0.0
-
-  mypy:
-    runs-on: ubuntu-latest
-    steps:
-
       - name: Checkout branch
         uses: actions/checkout@v4
 
       - name: Install apt packages
         run: |
           sudo apt update
-          sudo apt install -y libmemcached-dev
 
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
@@ -38,8 +30,8 @@ jobs:
       - name: Install Poetry
         uses: snok/install-poetry@v1.3.4
 
-      - name: Install tox and mypy
-        run: poetry install --with ci
+      - name: Install CI dependencies
+        run: poetry install --only ci
 
-      - name: Run mypy
-        run: tox -e mypy
+      - name: Run check
+        run: tox -e ${{ matrix.check }}

docs/Makefile

@@ -43,6 +43,7 @@ help:
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
 	@echo "  apicheck   to verify that all modules are present in autodoc"
 	@echo "  configcheck to verify that all modules are present in autodoc"
+	@echo "  apidoc     to regenerate API documentation with sphinx-apidoc"
 
 .PHONY: clean
 clean:
@@ -202,3 +203,15 @@ pseudoxml:
 .PHONY: livehtml
 livehtml:
 	sphinx-autobuild -b html --host 0.0.0.0 --port 7010 --watch $(APP) -c . $(SOURCEDIR) $(BUILDDIR)/html
+
+.PHONY: apidoc
+apidoc:
+	# Remove the existing reference directory
+	@rm -rf $(SOURCEDIR)/reference
+	# Generate new .rst files with sphinx-apidoc
+	@sphinx-apidoc -o $(SOURCEDIR)/reference $(SOURCEDIR)/../src -H "API Documentation"
+	# Rename modules.rst to index.rst
+	@mv $(SOURCEDIR)/reference/modules.rst $(SOURCEDIR)/reference/index.rst
+	# Add the .. _apiref: line to the beginning of index.rst
+	@echo ".. _apiref:\n\n$$(cat $(SOURCEDIR)/reference/index.rst)" > $(SOURCEDIR)/reference/index.rst
+	@echo "API documentation regenerated."

docs/conf.py

@@ -4,7 +4,7 @@
     conf.build_config(
         "pytest_celery",
         __file__,
-        project="Pytest Celery",
+        project="pytest_celery",
         version_dev="1.1",
         version_stable="1.0",
         canonical_url="https://pytest-celery.readthedocs.io/",
@@ -23,7 +23,20 @@
             "celery.contrib.sphinx",
         ],
         apicheck_ignore_modules=[
-            "celery.contrib",
+            r"celery.contrib.*",
         ],
+        linkcheck_ignore=[r"^http://localhost"],
+        autodoc_mock_imports=[],
     )
 )
+
+settings = {}
+ignored_settings = {}
+
+
+def configcheck_project_settings():
+    return set(settings)
+
+
+def configcheck_should_ignore(setting):
+    return setting in ignored_settings

docs/copyright.rst

@@ -1,3 +1,5 @@
+.. _copyright:
+
 Copyright
 =========
 

docs/getting-started/introduction.rst

@@ -8,7 +8,117 @@
     :local:
     :depth: 1
 
-TBD?
-====
+What's a Pytest Plugin?
+=======================
 
-TBD.
+TBD
+
+What do I need?
+===============
+
+.. sidebar:: Version Requirements
+    :subtitle: Pytest Celery version 1.0 runs on
+
+    - Python ❨3.8, 3.9, 3.10, 3.11, 3.12❩
+
+    Latest celery version comes out of the box but it is recommended to use your own version.
+
+    Pytest Celery is a project with minimal funding,
+    so we don't support Microsoft Windows.
+    Please don't open any issues related to that platform.
+
+TBD
+
+TODO: Comment about pytest-docker-tools dependency
+
+Get Started
+===========
+
+Until the documentation is ready, you can check the following locations
+for useful information (in order of usefulness):
+
+- CI_ configuration files.
+- Examples_ directory.
+- Tests_ directory.
+- Source_ code.
+
+.. _CI: https://github.com/celery/pytest-celery/tree/main/.github/workflows
+.. _Examples: https://github.com/celery/pytest-celery/tree/main/examples
+.. _Tests: https://github.com/celery/pytest-celery/tree/main/tests
+.. _Source: https://github.com/celery/pytest-celery/tree/main/src/pytest_celery
+
+Pytest Celery is…
+=================
+
+.. topic:: \
+
+    - **Simple**
+
+        See example below:
+
+        .. code-block:: python
+
+            def test_hello_world(celery_setup):
+                assert celery_setup.ready()
+
+    - **In development**
+
+        As you can see, the documentation is under construction.
+
+
+.. topic:: It supports
+
+    .. hlist::
+        :columns: 2
+
+        - **Cool Stuff**
+
+            - Highlights.
+            - More highlights.
+
+        - **Celery Stuff**
+
+            - Testing infra capabilities.
+
+Features
+========
+
+.. topic:: \
+
+    .. hlist::
+        :columns: 2
+
+        - **Pytest**
+
+            This is a pytest plugin.
+
+            :ref:`Read more… <faq>`.
+
+        - **Celery**
+
+            For Celery.
+
+            :ref:`Read more… <faq>`.
+
+Quick Jump
+==========
+
+.. topic:: I want to ⟶
+
+    .. hlist::
+        :columns: 2
+
+        - :ref:`To read Contributing <contributing>`
+        - :ref:`To read FAQ <faq>`
+        - :ref:`To read API Reference <apiref>`
+
+.. topic:: Jump to ⟶
+
+    .. hlist::
+        :columns: 4
+
+        - :ref:`Contributing <contributing>`
+        - :ref:`FAQ <faq>`
+        - :ref:`API Reference <apiref>`
+
+.. include:: ../includes/installation.txt

docs/glossary.rst

@@ -0,0 +1,10 @@
+.. _glossary:
+
+Glossary
+========
+
+.. glossary::
+    :sorted:
+
+    tbd
+        To be defined.

docs/includes/installation.txt

@@ -0,0 +1,24 @@
+.. _pytest_celery-installation:
+
+Installation
+============
+
+You can install Pytest Celery either via the Python Package Index (PyPI).
+
+To install using :command:`pip`:
+
+.. code-block:: console
+
+    $ pip install -U pytest-celery
+
+.. _pytest_celery-installing-from-git:
+
+Using the development version
+-----------------------------
+
+TBD
+
+With git
+~~~~~~~~
+
+Please see the :ref:`Contributing <contributing>` section.

docs/index.rst

@@ -1,7 +1,11 @@
 ===================================================
- pytest-celery - Official pytest plugin for Celery
+ Pytest Celery - Official pytest plugin for Celery
 ===================================================
 
+.. warning::
+
+    Documentation under construction!
+
 Welcome to pytest-celery, the official pytest plugin for Celery.
 
 Pytest Celery is Open Source and licensed under the `BSD License`_.
@@ -13,17 +17,16 @@ Donations
 
 This project relies on your generous donations.
 
-If you are using Pytest Celery to test a commercial product, please consider becoming our `backer`_ or our `sponsor`_ to ensure Pytest Celery's future.
+If you are using Pytest Celery to test a commercial product, please consider becoming
+our `backer`_ or our `sponsor`_ to ensure Pytest Celery's future.
 
-.. _`backer`: https://opencollective.com/celery#backer
-.. _`sponsor`: https://opencollective.com/celery#sponsor
+.. _`backer`: https://opencollective.com/celery
+.. _`sponsor`: https://opencollective.com/celery
 
 Getting Started
 ===============
 
-- If you're new to Celery you can get started by following
-  the :ref:`first-steps` tutorial.
-
+- If you're new to pytest-celery you can get started by following the :ref:`getting-started` tutorial.
 - You can also check out the :ref:`FAQ <faq>`.
 
 Contents
@@ -34,25 +37,24 @@ Contents
 
     copyright
 
-.. toctree::
-    :maxdepth: 1
-
-    getting-started/index
-
 .. toctree::
     :maxdepth: 2
 
+    getting-started/index
     userguide/index
 
 .. toctree::
     :maxdepth: 1
 
+    reference/index
+    contributing
     faq
     changelog
-    contributing
+    glossary
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
+* :ref:`modindex`
 * :ref:`search`

docs/reference/index.rst

@@ -0,0 +1,9 @@
+.. _apiref:
+
+API Documentation
+=================
+
+.. toctree::
+   :maxdepth: 4
+
+   pytest_celery