docs: modernize Sphinx config and fix broken cross-references

docs/_static/.gitkeep

@@ -0,0 +1,3 @@
+# Placeholder so Sphinx html_static_path does not warn about a missing
+# directory. Drop custom CSS/JS/images here and they will be copied into the
+# built site.

docs/async.rst

@@ -3,12 +3,13 @@ Async usage
 
 If your application uses an :class:`~sqlalchemy.ext.asyncio.AsyncSession`
 instead of a synchronous ``Session``, use the async seeders. ``AsyncSeeder``
-and ``AsyncHybridSeeder`` mirror :class:`~sqlalchemyseed.Seeder` and
-:class:`~sqlalchemyseed.HybridSeeder`: they accept the same entities and expose
-the same ``instances`` property, but their ``seed`` method is awaitable.
+and ``AsyncHybridSeeder`` mirror :class:`~sqlalchemyseed.seeder.Seeder` and
+:class:`~sqlalchemyseed.seeder.HybridSeeder`: they accept the same entities and
+expose the same ``instances`` property, but their ``seed`` method is awaitable.
 
 Under the hood they run the existing synchronous seeding logic through
-:meth:`AsyncSession.run_sync`, so a ``filter`` key still issues a real query --
+:meth:`~sqlalchemy.ext.asyncio.AsyncSession.run_sync`, so a ``filter`` key still
+issues a real query --
 executed against your async driver -- during the seed traversal.
 
 Installation
@@ -52,7 +53,8 @@ AsyncHybridSeeder
 -----------------
 
 Use ``AsyncHybridSeeder`` when the entities contain a ``filter`` key, just as
-you would reach for :class:`~sqlalchemyseed.HybridSeeder` in synchronous code.
+you would reach for :class:`~sqlalchemyseed.seeder.HybridSeeder` in synchronous
+code.
 
 .. code-block:: python
 

docs/conf.py

@@ -1,67 +1,62 @@
 # Configuration file for the Sphinx documentation builder.
 #
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
+# For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
-sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+from datetime import datetime, timezone
 
 project = 'sqlalchemyseed'
-copyright = '2022, jedymatt'
 author = 'jedymatt'
+copyright = f'2022–{datetime.now(timezone.utc):%Y}, {author}'
 
 
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
-    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'autoapi.extension',
     'sphinx_copybutton',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
+# Patterns, relative to the source directory, to ignore when looking for source
+# files. Also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
+# -- Options for intersphinx -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 #
-# html_theme = 'alabaster'
-html_theme = 'furo'
+# Lets cross-references such as :class:`~sqlalchemy.ext.asyncio.AsyncSession`
+# resolve to the upstream documentation instead of rendering as dead text.
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'sqlalchemy': ('https://docs.sqlalchemy.org/en/20/', None),
+}
 
-# autoapi.extension configuration
-extensions.append('autoapi.extension')
 
-autoapi_type = 'python'
+# -- Options for AutoAPI -----------------------------------------------------
+# https://sphinx-autoapi.readthedocs.io/en/latest/reference/config.html
+#
+# AutoAPI reads the source tree statically, so the package does not need to be
+# importable (or its runtime dependencies installed) to build the docs.
+
 autoapi_dirs = ['../src']
 autoapi_options = ['members', 'undoc-members', 'show-inheritance']
-autoapi_add_toctree_entry = True
-autoapi_generate_api_docs = True
-autoapi_root = 'api'
-autoapi_file_patterns = ['*.py']
 autoapi_member_order = 'groupwise'
+# Keep the generated API pages under /api/ (AutoAPI defaults to /autoapi/);
+# changing this would break existing inbound links.
+autoapi_root = 'api'
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']

docs/requirements.txt

@@ -1,11 +1,14 @@
-sphinx>=4.3
+# Documentation build dependencies.
+# See .readthedocs.yaml for how these are installed on Read the Docs.
 
-# Themes
+sphinx>=8.0
+
+# Theme
 furo
 
-# Extentions
+# Extensions
 sphinx-copybutton
 sphinx-autoapi
 
-# Others
+# Local live-reload builds: `sphinx-autobuild docs docs/_build/html`
 sphinx-autobuild

src/sqlalchemyseed/aio.py

@@ -2,8 +2,9 @@
 Async wrappers around the synchronous seeders.
 
 These bridge the existing sync-only seeder logic onto an ``AsyncSession``
-using :meth:`AsyncSession.run_sync`, which runs the sync code inside a
-greenlet where the driver's blocking I/O is translated into ``await`` calls.
+using :meth:`~sqlalchemy.ext.asyncio.AsyncSession.run_sync`, which runs the
+sync code inside a greenlet where the driver's blocking I/O is translated
+into ``await`` calls.
 No parallel async reimplementation of the traversal is needed.
 """