docs: add api docs (#27)

Co-authored-by: Cody Fincher <204685+cofin@users.noreply.github.com>
litestar-org · Sep 17, 2023 · f70a037 · f70a037
1 parent b8952a2
commit f70a037
Show file tree

Hide file tree

Showing 46 changed files with 402 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -43,6 +43,9 @@ offering features such as:
 
 ## Usage
 
+> [!IMPORTANT]\
+> Check out [the installation guide][install-guide] in our official documentation!
+
 ### Litestar
 
 > [!NOTE]\
@@ -83,3 +86,4 @@ or the [project-specific GitHub discussions page][project-discussions].
 [jolt-discussions]: https://github.com/orgs/jolt-org/discussions
 [project-discussions]: https://github.com/jolt-org/advanced-alchemy/discussions
 [project-docs]: https://docs.advanced-alchemy.jolt.rs
+[install-guide]: https://docs.advanced-alchemy.jolt.rs/latest/#installation
diff --git a/advanced_alchemy/config/common.py b/advanced_alchemy/config/common.py
@@ -27,10 +27,15 @@
 )
 
 ALEMBIC_TEMPLATE_PATH = f"{Path(__file__).parent.parent}/alembic/templates"
+"""Path to the Alembic templates."""
 ConnectionT = TypeVar("ConnectionT", bound="Connection | AsyncConnection")
+"""Type variable for a SQLAlchemy connection."""
 EngineT = TypeVar("EngineT", bound="Engine | AsyncEngine")
+"""Type variable for a SQLAlchemy engine."""
 SessionT = TypeVar("SessionT", bound="Session | AsyncSession")
+"""Type variable for a SQLAlchemy session."""
 SessionMakerT = TypeVar("SessionMakerT", bound="sessionmaker | async_sessionmaker")
+"""Type variable for a SQLAlchemy sessionmaker."""
 
 
 @dataclass
@@ -187,10 +192,12 @@ class GenericAlembicConfig:
     will be used.
     """
     version_table_name: str = "alembic_versions"
-    """Configure the name of the table used to hold the applied alembic revisions. Defaults to ``alembic_versions``.  THe name of the table
+    """Configure the name of the table used to hold the applied alembic revisions.
+    Defaults to ``alembic_versions``.
     """
     version_table_schema: str | None = None
-    """Configure the schema to use for the alembic revisions revisions. If unset, it defaults to connection's default schema."""
+    """Configure the schema to use for the alembic revisions revisions.
+    If unset, it defaults to connection's default schema."""
     script_location: str = "migrations"
     """A path to save generated migrations.
     """

diff --git a/advanced_alchemy/config/types.py b/advanced_alchemy/config/types.py
@@ -1,3 +1,4 @@
+"""Type aliases and constants used in the package config."""
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Callable, Literal, Mapping, Sequence, Type, final
@@ -7,6 +8,14 @@
 
 
 def filter_empty(obj: dict[Any, Any]) -> dict[Any, Any]:
+    """Filter out empty values from a dictionary.
+
+    Args:
+        obj: The dictionary to filter.
+
+    Returns:
+        The filtered dictionary.
+    """
     return {k: filter_empty(v) if isinstance(v, dict) else v for k, v in obj.items() if v is not Empty}
 
 
@@ -16,7 +25,10 @@ class Empty:
 
 
 EmptyType: TypeAlias = Type[Empty]
+"""Type alias for the :class:`Empty` sentinel class."""
 TypeEncodersMap: TypeAlias = "Mapping[Any, Callable[[Any], Any]]"
+"""Type alias for a mapping of type encoders."""
 TypeDecodersSequence: TypeAlias = "Sequence[tuple[Callable[[Any], bool], Callable[[Any, Any], Any]]]"
-
+"""Type alias for a sequence of type decoders."""
 CommitStrategy = Literal["always", "match_status"]
+"""Commit strategy for SQLAlchemy sessions."""
diff --git a/advanced_alchemy/extensions/litestar/plugins/init/config/asyncio.py b/advanced_alchemy/extensions/litestar/plugins/init/config/asyncio.py
@@ -21,6 +21,8 @@
     from litestar import Litestar
     from litestar.datastructures.state import State
     from litestar.types import BeforeMessageSendHookHandler, Message, Scope
+
+    # noinspection PyUnresolvedReferences
     from litestar.types.asgi_types import HTTPResponseStartEvent
 
 

diff --git a/advanced_alchemy/extensions/litestar/plugins/init/config/common.py b/advanced_alchemy/extensions/litestar/plugins/init/config/common.py
@@ -1,4 +1,6 @@
 from litestar.constants import HTTP_DISCONNECT, HTTP_RESPONSE_START, WEBSOCKET_CLOSE, WEBSOCKET_DISCONNECT
 
 SESSION_SCOPE_KEY = "_sqlalchemy_db_session"
+"""Session scope key."""
 SESSION_TERMINUS_ASGI_EVENTS = {HTTP_RESPONSE_START, HTTP_DISCONNECT, WEBSOCKET_DISCONNECT, WEBSOCKET_CLOSE}
+"""ASGI events that terminate a session scope."""
diff --git a/docs/index.rst b/docs/index.rst
@@ -15,7 +15,39 @@ offering useful and easy-to-use features for your database projects.
 Installation
 ------------
 
-.. todo:: Add installation instructions
+Installing ``advanced-alchemy`` is as easy as calling your favorite Python package manager:
+
+.. tab-set::
+
+    .. tab-item:: pip
+        :sync: key1
+
+        .. code-block:: bash
+            :caption: Using pip
+
+            python3 -m pip install advanced-alchemy
+
+    .. tab-item:: pipx
+        :sync: key2
+
+        .. code-block:: bash
+            :caption: Using `pipx <https://pypa.github.io/pipx/>`_
+
+            pipx install advanced-alchemy
+
+    .. tab-item:: pdm
+
+        .. code-block:: bash
+            :caption: Using `PDM <https://pdm.fming.dev/>`_
+
+            pdm add advanced-alchemy
+
+    .. tab-item:: Poetry
+
+        .. code-block:: bash
+            :caption: Using `Poetry <https://python-poetry.org/>`_
+
+            poetry add advanced-alchemy
 
 Usage
 -----
@@ -28,12 +60,12 @@ Usage
     :hidden:
 
     usage/index
-    api/index
+    reference/index
 
 .. toctree::
     :titlesonly:
     :caption: Development
     :hidden:
 
-    contribution-guide
     changelog
+    contribution-guide
diff --git a/docs/reference/alembic/commands.rst b/docs/reference/alembic/commands.rst
@@ -0,0 +1,6 @@
+========
+commands
+========
+
+.. automodule:: advanced_alchemy.alembic.commands
+    :members:
diff --git a/docs/reference/alembic/index.rst b/docs/reference/alembic/index.rst
@@ -0,0 +1,17 @@
+=======
+alembic
+=======
+
+API Reference for the ``Alembic`` module
+
+.. note:: Private methods and attributes are not included in the API reference.
+
+Available API References
+------------------------
+
+.. toctree::
+    :titlesonly:
+
+    commands
+    templates/asyncio/index
+    templates/sync/index
diff --git a/docs/reference/alembic/templates/asyncio/alembic-ini.rst b/docs/reference/alembic/templates/asyncio/alembic-ini.rst
@@ -0,0 +1,7 @@
+===========
+alembic.ini
+===========
+
+.. literalinclude:: ../../../../../advanced_alchemy/alembic/templates/asyncio/alembic.ini.mako
+    :language: ini
+    :linenos:
diff --git a/docs/reference/alembic/templates/asyncio/env.rst b/docs/reference/alembic/templates/asyncio/env.rst
@@ -0,0 +1,6 @@
+===
+env
+===
+
+.. automodule:: advanced_alchemy.alembic.templates.asyncio.env
+    :members:
diff --git a/docs/reference/alembic/templates/asyncio/index.rst b/docs/reference/alembic/templates/asyncio/index.rst
@@ -0,0 +1,17 @@
+=======
+asyncio
+=======
+
+API Reference for the ``Alembic.Templates.Asyncio`` module
+
+.. note:: Private methods and attributes are not included in the API reference.
+
+Available API References
+------------------------
+
+.. toctree::
+    :titlesonly:
+
+    alembic-ini
+    env
+    script-py
diff --git a/docs/reference/alembic/templates/asyncio/script-py.rst b/docs/reference/alembic/templates/asyncio/script-py.rst
@@ -0,0 +1,7 @@
+=========
+script.py
+=========
+
+.. literalinclude:: ../../../../../advanced_alchemy/alembic/templates/asyncio/script.py.mako
+    :language: python
+    :linenos:
diff --git a/docs/reference/alembic/templates/sync/alembic-ini.rst b/docs/reference/alembic/templates/sync/alembic-ini.rst
@@ -0,0 +1,7 @@
+===========
+alembic.ini
+===========
+
+.. literalinclude:: ../../../../../advanced_alchemy/alembic/templates/sync/alembic.ini.mako
+    :language: ini
+    :linenos:
diff --git a/docs/reference/alembic/templates/sync/env.rst b/docs/reference/alembic/templates/sync/env.rst
@@ -0,0 +1,6 @@
+===
+env
+===
+
+.. automodule:: advanced_alchemy.alembic.templates.sync.env
+    :members:
diff --git a/docs/reference/alembic/templates/sync/index.rst b/docs/reference/alembic/templates/sync/index.rst
@@ -0,0 +1,17 @@
+====
+sync
+====
+
+API Reference for the ``Alembic.Templates.Sync`` module
+
+.. note:: Private methods and attributes are not included in the API reference.
+
+Available API References
+------------------------
+
+.. toctree::
+    :titlesonly:
+
+    alembic-ini
+    env
+    script-py
diff --git a/docs/reference/alembic/templates/sync/script-py.rst b/docs/reference/alembic/templates/sync/script-py.rst
@@ -0,0 +1,7 @@
+=========
+script.py
+=========
+
+.. literalinclude:: ../../../../../advanced_alchemy/alembic/templates/sync/script.py.mako
+    :language: python
+    :linenos:
diff --git a/docs/reference/base.rst b/docs/reference/base.rst
@@ -0,0 +1,6 @@
+====
+base
+====
+
+.. automodule:: advanced_alchemy.base
+    :members:
diff --git a/docs/reference/config/asyncio.rst b/docs/reference/config/asyncio.rst
@@ -0,0 +1,6 @@
+=======
+asyncio
+=======
+
+.. automodule:: advanced_alchemy.config.asyncio
+    :members:
diff --git a/docs/reference/config/common.rst b/docs/reference/config/common.rst
@@ -0,0 +1,6 @@
+======
+common
+======
+
+.. automodule:: advanced_alchemy.config.common
+    :members:
diff --git a/docs/reference/config/engine.rst b/docs/reference/config/engine.rst
@@ -0,0 +1,6 @@
+======
+engine
+======
+
+.. automodule:: advanced_alchemy.config.engine
+    :members:
diff --git a/docs/reference/config/index.rst b/docs/reference/config/index.rst
@@ -0,0 +1,19 @@
+======
+config
+======
+
+API Reference for the ``Config`` module
+
+.. note:: Private methods and attributes are not included in the API reference.
+
+Available API References
+------------------------
+
+.. toctree::
+    :titlesonly:
+
+    asyncio
+    common
+    engine
+    sync
+    types
diff --git a/docs/reference/config/sync.rst b/docs/reference/config/sync.rst
@@ -0,0 +1,6 @@
+====
+sync
+====
+
+.. automodule:: advanced_alchemy.config.sync
+    :members:
diff --git a/docs/reference/config/types.rst b/docs/reference/config/types.rst
@@ -0,0 +1,6 @@
+=====
+types
+=====
+
+.. automodule:: advanced_alchemy.config.types
+    :members:
diff --git a/docs/reference/exceptions.rst b/docs/reference/exceptions.rst
@@ -1,3 +1,4 @@
+==========
 exceptions
 ==========
 

diff --git a/docs/reference/extensions/index.rst b/docs/reference/extensions/index.rst
@@ -0,0 +1,17 @@
+==========
+extensions
+==========
+
+API Reference for the ``Extensions`` module
+
+.. note:: Private methods and attributes are not included in the API reference.
+
+Available API References
+------------------------
+
+.. toctree::
+    :titlesonly:
+
+    litestar/index
+    sanic
+    starlette
diff --git a/docs/reference/extensions/litestar/alembic.rst b/docs/reference/extensions/litestar/alembic.rst
@@ -0,0 +1,6 @@
+=======
+alembic
+=======
+
+.. automodule:: advanced_alchemy.extensions.litestar.alembic
+    :members:
diff --git a/docs/reference/extensions/litestar/cli.rst b/docs/reference/extensions/litestar/cli.rst
@@ -0,0 +1,7 @@
+===
+cli
+===
+
+.. click:: advanced_alchemy.extensions.litestar.cli:database_group
+    :prog: Litestar CLI
+    :nested: full
diff --git a/docs/reference/extensions/litestar/dto.rst b/docs/reference/extensions/litestar/dto.rst
@@ -0,0 +1,6 @@
+===
+dto
+===
+
+.. automodule:: advanced_alchemy.extensions.litestar.dto
+    :members:
diff --git a/docs/reference/extensions/litestar/index.rst b/docs/reference/extensions/litestar/index.rst
@@ -0,0 +1,18 @@
+========
+litestar
+========
+
+API Reference for the ``Litestar`` extensions module
+
+.. note:: Private methods and attributes are not included in the API reference.
+
+Available API References
+------------------------
+
+.. toctree::
+    :titlesonly:
+
+    alembic
+    cli
+    dto
+    plugins/index