Updated and fixed the documentation

.readthedocs.yml

@@ -7,6 +7,7 @@ build:
 
 sphinx:
   configuration: docs/conf.py
+  fail_on_warning: true
 
 python:
    install:

docs/api.rst

@@ -7,6 +7,7 @@ Data structures
 .. autoclass:: apscheduler.Task
 .. autoclass:: apscheduler.TaskDefaults
 .. autoclass:: apscheduler.Schedule
+.. autoclass:: apscheduler.ScheduleResult
 .. autoclass:: apscheduler.Job
 .. autoclass:: apscheduler.JobResult
 

docs/conf.py

@@ -50,10 +50,19 @@
     "cbor2",
     "paho",
     "pymongo",
+    "psycopg",
     "redis",
     "sqlalchemy",
     "PyQt6",
 ]
+autodoc_type_aliases = {
+    "datetime": "datetime.datetime",
+    "UUID": "uuid.UUID",
+    "AsyncEngine": "sqlalchemy.ext.asyncio.AsyncEngine",
+    "RetrySettings": "apscheduler.RetrySettings",
+    "Serializer": "apscheduler.abc.Serializer",
+}
+nitpick_ignore = [("py:class", "datetime")]
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -65,5 +74,10 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "anyio": ("https://anyio.readthedocs.io/en/latest/", None),
+    "asyncpg": ("https://magicstack.github.io/asyncpg/current/", None),
+    "cbor2": ("https://cbor2.readthedocs.io/en/latest/", None),
+    "psycopg": ("https://www.psycopg.org/psycopg3/docs/", None),
+    "pymongo": ("https://pymongo.readthedocs.io/en/stable", None),
+    "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
     "tenacity": ("https://tenacity.readthedocs.io/en/latest/", None),
 }

docs/userguide.rst

@@ -482,9 +482,9 @@ be sent to all schedulers and workers connected to that event broker.
 Clean-up of expired jobs, job results and schedules
 ===================================================
 
-Each scheduler runs the data store's :meth:`~DataStore.cleanup` method periodically,
-configurable via the ``cleanup_interval`` scheduler parameter. This ensures that the
-data store doesn't get filled with unused data over time.
+Each scheduler runs the data store's :meth:`~.abc.DataStore.cleanup` method
+periodically, configurable via the ``cleanup_interval`` scheduler parameter. This
+ensures that the data store doesn't get filled with unused data over time.
 
 Deployment
 ==========

pyproject.toml

@@ -136,5 +136,5 @@ commands = pyright --verifytypes apscheduler
 
 [testenv:docs]
 extras = doc
-commands = sphinx-build -n docs build/sphinx
+commands = sphinx-build -W -n docs build/sphinx
 """

src/apscheduler/__init__.py

@@ -28,6 +28,7 @@
 from ._events import TaskAdded as TaskAdded
 from ._events import TaskRemoved as TaskRemoved
 from ._events import TaskUpdated as TaskUpdated
+from ._exceptions import CallableLookupError as CallableLookupError
 from ._exceptions import ConflictingIdError as ConflictingIdError
 from ._exceptions import DeserializationError as DeserializationError
 from ._exceptions import JobCancelled as JobCancelled
@@ -45,8 +46,10 @@
 from ._structures import Job as Job
 from ._structures import JobResult as JobResult
 from ._structures import Schedule as Schedule
+from ._structures import ScheduleResult as ScheduleResult
 from ._structures import Task as Task
 from ._structures import TaskDefaults as TaskDefaults
+from ._utils import UnsetValue as UnsetValue
 
 # Re-export imports, so they look like they live directly in this package
 value: Any

src/apscheduler/_schedulers/async_.py

@@ -307,7 +307,7 @@ async def configure_task(
         max_running_jobs: int | None | UnsetValue = unset,
     ) -> Task:
         """
-        Add or update a :ref:`task` definition.
+        Add or update a :ref:`task <task>` definition.
 
         Any options not explicitly passed to this method will use their default values
         (from ``task_defaults``) when a new task is created:

src/apscheduler/datastores/sqlalchemy.py

@@ -129,7 +129,7 @@ class SQLAlchemyDataStore(BaseExternalDataStore):
     if they're not already present.
 
     Operations are retried (in accordance to ``retry_settings``) when an operation
-    raises :exc:`sqlalchemy.OperationalError`.
+    raises either :exc:`OSError` or :exc:`sqlalchemy.exc.InterfaceError`.
 
     This store has been tested to work with:
 

src/apscheduler/eventbrokers/asyncpg.py

@@ -35,7 +35,7 @@ class AsyncpgEventBroker(BaseExternalEventBroker):
 
     :param dsn: a libpq connection string (e.g.
         ``postgres://user:pass@host:port/dbname``)
-    :param options: extra keyword arguments passed to :func:`asyncpg.connect`
+    :param options: extra keyword arguments passed to :func:`asyncpg.connection.connect`
     :param channel: the ``NOTIFY`` channel to use
     :param max_idle_time: maximum time to let the connection go idle, before sending a
         ``SELECT 1`` query to prevent a connection timeout
@@ -61,11 +61,12 @@ def from_async_sqla_engine(
         Create a new asyncpg event broker from an SQLAlchemy engine.
 
         The engine will only be used to create the appropriate options for
-        :func:`asyncpg.connect`.
+        :func:`asyncpg.connection.connect`.
 
         :param engine: an asynchronous SQLAlchemy engine using asyncpg as the driver
         :type engine: ~sqlalchemy.ext.asyncio.AsyncEngine
-        :param options: extra keyword arguments passed to :func:`asyncpg.connect`
+        :param options: extra keyword arguments passed to
+            :func:`asyncpg.connection.connect`
         :param kwargs: keyword arguments to pass to the initializer of this class
         :return: the newly created event broker
 

src/apscheduler/eventbrokers/psycopg.py

@@ -35,7 +35,7 @@ class PsycopgEventBroker(BaseExternalEventBroker):
     An asynchronous, psycopg_ based event broker that uses a PostgreSQL server to
     broadcast events using its ``NOTIFY`` mechanism.
 
-    .. psycopg: https://pypi.org/project/psycopg/
+    .. _psycopg: https://pypi.org/project/psycopg/
 
     :param conninfo: a libpq connection string (e.g.
         ``postgres://user:pass@host:port/dbname``)