Merge pull request #299 from lsst-sqre/tickets/DM-46034

DM-46034: Add support functions for Alembic

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Association of Universities for Research in Astronomy, Inc. (AURA)
+Copyright (c) 2020-2024 Association of Universities for Research in Astronomy, Inc. (AURA)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/api.rst

@@ -72,8 +72,14 @@ API reference
 .. automodapi:: safir.middleware.x_forwarded
    :include-all-objects:
 
+..
+   If all objects from safir.pydantic are included, the pages for the
+   Pydantic types are generated but not linked into any table of contents.
+   This is probably a but in automodapi and should be checked against later
+   verisons to see if it's fixed. Once this is fixed, the nitpick exclusions
+   in documenteer.yaml can also be removed.
+
 .. automodapi:: safir.pydantic
-   :include-all-objects:
 
 .. automodapi:: safir.redis
    :include-all-objects:

docs/documenteer.toml

@@ -1,6 +1,6 @@
 [project]
 title = "Safir"
-copyright = "2020-2023 Association of Universities for Research in Astronomy, Inc. (AURA)"
+copyright = "2020-2024 Association of Universities for Research in Astronomy, Inc. (AURA)"
 
 [project.python]
 package = "safir"
@@ -17,19 +17,20 @@ nitpick_ignore_regex = [
     ['py:.*', 'starlette.*'],
 ]
 nitpick_ignore = [
-    ['py:class', 'unittest.mock.Base'],
-    ['py:class', 'unittest.mock.CallableMixin'],
+    # These don't appear to have documentation but show up in the inheritance
+    # tree.
+    ["py:class", "unittest.mock.Base"],
+    ["py:class", "unittest.mock.CallableMixin"],
+    # autodoc_pydantic generates some spurious links that can't be resolved.
     ["py:obj", "ComputedFieldInfo"],
-    ["py:obj", "JobMetadata.id"],
-    ["py:class", "pydantic.BaseModel"],
-    ["py:class", "BaseModel"],
+    ["py:class", "lambda"],
     # arq doesn't provide documentation for all of its types.
     ["py:class", "arq.cron.CronJob"],
     ["py:class", "arq.typing.StartupShutdown"],
     ["py:class", "arq.typing.WorkerCoroutine"],
     ["py:class", "arq.worker.Function"],
-    # sphinx-automodapi apparently doesn't recognize TypeAlias as an object
-    # that should have generated documentation, even with include-all-objects.
+    # Including the documentation for these generates the pages but doesn't
+    # include them in the table of contents, so for now they're excluded.
     ["py:obj", "safir.pydantic.EnvAsyncPostgresDsn"],
     ["py:obj", "safir.pydantic.EnvRedisDsn"],
     ["py:obj", "safir.pydantic.HumanTimedelta"],
@@ -39,6 +40,13 @@ nitpick_ignore = [
     # submodules.
     ["py:obj", "safir.asyncio._multiqueue.T"],
     ["py:obj", "safir.redis._storage.S"],
+    # SQLAlchemy DeclarativeBase documentation has references that Sphinx
+    # can't resolve properly.
+    ["py:class", "sqlalchemy.inspection.Inspectable"],
+    ["py:class", "_orm.Mapper"],
+    ["py:class", "_orm.registry"],
+    ["py:class", "_schema.MetaData"],
+    ["py:class", "_schema.Table"],
 ]
 extensions = [
     "sphinxcontrib.autodoc_pydantic",

docs/user-guide/database/index.rst

@@ -26,3 +26,4 @@ Guides
    datetime
    retry
    testing
+   schema

docs/user-guide/database/initialize.rst

@@ -55,6 +55,8 @@ If ``config.database_schema`` is `None`, the default schema will be used; otherw
 Safir supports this in database initialization by creating a non-default schema if one is set.
 If the ``schema`` attribute is set (via code like the above) on the SQLAlchemy metadata passed to the ``schema`` parameter of `~safir.database.initialize_database`, it will create that schema in the PostgreSQL database if it does not already exist.
 
+.. _database-init-cli:
+
 Add a CLI command to initialize the database
 ============================================
 
@@ -80,7 +82,7 @@ For applications using Click_ (the recommended way to implement a command-line i
        "--reset", is_flag=True, help="Delete all existing database data."
    )
    @run_with_asyncio
-   async def init(reset: bool) -> None:
+   async def init(*, reset: bool) -> None:
        logger = structlog.get_logger(config.logger_name)
        engine = create_database_engine(
            config.database_url, config.database_password