Add Sphinx documentation site with ReadTheDocs setup (#13)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: knifecake

.gitignore

@@ -18,3 +18,6 @@ wheels/
 # temporary files
 tmp/
 .mypy_cache/
+
+# Sphinx docs build output
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv 0.10.2
+    - asdf global uv 0.10.2
+    - uv sync --group docs --frozen
+    - uv run -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+**Added:**
+
+- Sphinx documentation site covering installation, getting started,
+  configuration, API reference, internals and alternatives (#13). Published
+  to Read The Docs.
+
 **Fixed:**
 
 - Fixed a bug where the process would hang on shutdown and require `kill -9`.

Makefile

@@ -13,6 +13,10 @@ lint:
 	uv run ruff check --fix
 	uv run ruff format
 
+.PHONY: docs
+docs:
+	uv run --group docs -m sphinx -b html docs docs/_build/html
+
 .PHONY: force-kill
 force-kill:
 	ps | grep steady_queue | cut -f 1  -d ' '  | xargs kill -9

docs/Makefile

@@ -0,0 +1,14 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= uv run sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/alternatives.rst

@@ -0,0 +1,88 @@
+============
+Alternatives
+============
+
+.. contents:: On this page
+   :local:
+   :depth: 2
+
+vs django-tasks
+---------------
+
+`django-tasks <https://github.com/RealOrangeOne/django-tasks>`_ is the
+third-party package that defined the ``django.tasks`` interface (DEP 0014) and
+served as its reference implementation. It ships a ``DatabaseBackend`` that
+stores and executes tasks using your application's database.
+
+The ``django-tasks`` ``DatabaseBackend`` is intentionally minimal. Steady
+Queue is also a database-backed implementation of the same interface, but adds:
+
+- **Cron-style recurring tasks** via the ``@recurring`` decorator.
+- **Concurrency controls** via ``@limits_concurrency``.
+- **Operational visibility**: inspect, retry and discard failed tasks from the
+  Django admin.
+- **Queue pausing**: pause and resume individual queues from the admin.
+- **Horizontal scaling**: run multiple worker or dispatcher processes across
+  machines.
+- **Configurable process topology**: control the number of workers, threads per
+  worker, polling intervals and which queues each worker handles.
+- **Heartbeat-based liveness checks** with automatic task recovery when a
+  worker process dies.
+
+If you just need simple background task execution and none of the above
+features matter to you, ``django-tasks`` is a fine choice. Steady Queue is
+the better fit when you need more operational control or advanced features.
+
+Because both implement the same ``django.tasks`` interface, you can switch
+between them by changing a single line in ``settings.py``.
+
+vs Celery
+---------
+
+Celery is the most widely used task queue library in the Python ecosystem. It
+is mature, has a huge community and supports a wide range of brokers (Redis,
+RabbitMQ, Amazon SQS, etc.).
+
+The main trade-off is operational complexity: Celery requires a separate broker
+process (typically Redis or RabbitMQ) that must be deployed, monitored and
+maintained. Steady Queue uses your existing database, so there's nothing new to
+operate.
+
+Celery also has its own task definition interface (``@app.task`` / ``@shared_task``),
+whereas Steady Queue follows the standard ``django.tasks`` interface (DEP 0014),
+which keeps your task code portable across compliant backends.
+
+Consider Celery if you need features like task routing to heterogeneous worker
+pools, support for non-relational brokers, or the rich ecosystem of
+third-party Celery extensions. Consider Steady Queue if you'd rather not
+introduce a broker dependency and your workloads fit comfortably within a
+relational database.
+
+vs django-rq
+------------
+
+`django-rq <https://github.com/rq/django-rq>`_ integrates the `RQ
+<https://python-rq.org/>`_ task queue (which uses Redis as a broker) with
+Django. Like Celery, it requires Redis to be running. It is simpler than
+Celery and easier to set up, but still adds operational overhead compared to a
+pure database solution.
+
+vs Solid Queue
+--------------
+
+`Solid Queue <https://github.com/rails/solid_queue>`_ is the Ruby on Rails
+library that Steady Queue is ported from. If you're coming from a Rails
+background, the concepts and configuration will look familiar. The main
+differences in the external interface are:
+
+- **Task definition.** Solid Queue works with Active Job classes; Steady Queue
+  uses the ``@task`` decorator from DEP 0014.
+- **Priority ordering.** Steady Queue follows Django's convention where *larger*
+  numbers mean *higher* priority (e.g. priority 10 runs before priority 0).
+  Solid Queue uses the inverse.
+- **Recurring tasks.** Solid Queue supports command-based recurring tasks
+  (arbitrary shell commands on a schedule). Steady Queue only supports
+  recurring Python task functions.
+- **Instrumentation.** Solid Queue emits rich ``ActiveSupport::Notifications``
+  events. Steady Queue uses standard Python logging and the ``django.tasks``
+  signals instead.

docs/api.rst

@@ -0,0 +1,153 @@
+=============
+API Reference
+=============
+
+Steady Queue's public API is intentionally small. Most of the interface comes
+from Django's ``django.tasks`` module (see the `Django tasks documentation
+<https://docs.djangoproject.com/en/stable/ref/tasks/>`_). Steady Queue adds
+two decorators and a handful of module-level settings.
+
+.. contents:: On this page
+   :local:
+   :depth: 2
+
+
+.. _api-recurring:
+
+@recurring
+----------
+
+.. autofunction:: steady_queue.recurring_task.recurring
+
+The ``@recurring`` decorator registers a task to be enqueued automatically on
+a cron schedule. It must be applied *outside* the ``@task()`` decorator:
+
+.. code-block:: python
+
+    from django.tasks import task
+    from steady_queue.recurring_task import recurring
+
+    @recurring(schedule="0 9 * * 1-5", key="weekly_report")
+    @task()
+    def weekly_report():
+        ...
+
+The same task can have multiple recurring schedules:
+
+.. code-block:: python
+
+    @recurring(schedule="0 9 * * *", args=("Alice",), key="greet_alice")
+    @recurring(schedule="0 12 * * *", args=("Bob",), key="greet_bob")
+    @task()
+    def greet(name: str):
+        print(f"Hello, {name}!")
+
+Parameters:
+
+``schedule``
+    A crontab expression (anything understood by the `crontab
+    <https://pypi.org/project/crontab/>`_ library). For example:
+
+    - ``"* * * * *"`` — every minute
+    - ``"0 9 * * 1-5"`` — 9am on weekdays
+    - ``"@daily"`` — once a day at midnight
+
+``key``
+    A unique string identifier for this recurring configuration. Must be
+    unique across all ``@recurring`` decorators in your codebase. Used to
+    prevent duplicate runs when multiple schedulers are active.
+
+``args``
+    Positional arguments to pass to the task when it is enqueued. Defaults to
+    no arguments.
+
+``kwargs``
+    Keyword arguments to pass to the task when it is enqueued.
+
+``queue_name``
+    The queue to enqueue the task on. If omitted, uses the queue from the
+    ``@task()`` decorator or the default queue.
+
+``priority``
+    Numeric priority for the enqueued task. If omitted, uses the priority from
+    the ``@task()`` decorator or ``0``.
+
+``description``
+    Optional human-readable description. Currently unused but stored for
+    future tooling.
+
+
+.. _api-limits-concurrency:
+
+@limits_concurrency
+-------------------
+
+.. autofunction:: steady_queue.concurrency.limits_concurrency
+
+The ``@limits_concurrency`` decorator restricts how many instances of a task
+can run at the same time. It must be applied *outside* the ``@task()``
+decorator:
+
+.. code-block:: python
+
+    from django.tasks import task
+    from steady_queue.concurrency import limits_concurrency
+
+    @limits_concurrency(key=lambda user_id: str(user_id), to=1)
+    @task()
+    def generate_report(user_id: int):
+        ...
+
+Parameters:
+
+``key``
+    **Required.** A string or a callable that accepts the same arguments as
+    the task and returns a string. Tasks with the same key value are counted
+    together for the concurrency limit.
+
+``to``
+    Maximum number of tasks with the same key that may run simultaneously.
+    Defaults to ``1``.
+
+``duration``
+    How long the concurrency guarantee is held. If a task holds a concurrency
+    slot for longer than this, the slot may be released by the dispatcher's
+    maintenance pass. Defaults to
+    ``steady_queue.default_concurrency_control_period`` (3 minutes).
+
+``group``
+    A string used to apply a shared concurrency limit across different task
+    types. Tasks from different functions that share the same ``group`` and
+    ``key`` value count against the same limit. Defaults to the task's module
+    path.
+
+
+Argument serialization
+----------------------
+
+Task functions accept almost any argument type as positional or keyword
+arguments. Beyond the standard DEP 0014 serializable types, Steady Queue adds
+support for:
+
+- ``datetime`` and ``date`` objects
+- ``timedelta`` objects
+- Django model instances (serialized as content type + primary key)
+
+If a model instance cannot be found in the database when the task is executed,
+a ``steady_queue.arguments.DeserializationError`` is raised.
+
+
+Backend limitations
+-------------------
+
+The ``SteadyQueueBackend`` does not support the following features defined by
+the Django task backend interface:
+
+- **Async enqueueing** — tasks cannot be enqueued from async code.
+- **Result fetching** — ``task_result.return_value`` is not supported. Store
+  results directly in your database or file storage if they need to be
+  persisted.
+
+These limitations are advertised via the
+`Django task feature flags
+<https://docs.djangoproject.com/en/stable/ref/tasks/#feature-flags>`_.

docs/conf.py

@@ -0,0 +1,48 @@
+import os
+import sys
+
+import django
+
+project = "Steady Queue"
+copyright = "2025, Elias Hernandis"
+author = "Elias Hernandis"
+
+# Make source available for autodoc
+os.environ["DJANGO_SETTINGS_MODULE"] = "tests.settings"
+sys.path.insert(0, os.path.abspath(".."))
+django.setup()
+
+import steady_queue  # noqa: E402
+
+release = steady_queue.__version__
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+templates_path = ["_templates"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]
+
+html_theme_options = {
+    "description": "A database-backed task backend for Django",
+    "github_user": "knifecake",
+    "github_repo": "steady-queue",
+    "github_button": True,
+    "github_type": "star",
+}
+
+# -- Napoleon extension configuration ----------------------------------------
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False