docs: complete reference documentation overhaul and fix critical issues

.github/workflows/ci.yml

@@ -181,8 +181,18 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Build docs
+        env:
+          PR_NUMBER: ${{ github.event.number }}
         run: uv run make docs
 
+      - name: Ensure .nojekyll present
+        # GitHub Pages runs Jekyll by default which ignores files/dirs starting with
+        # an underscore (e.g. _static). Creating a .nojekyll file prevents that and
+        # ensures Sphinx assets are served on the docs preview site.
+        run: |
+          mkdir -p docs/_build/html
+          touch docs/_build/html/.nojekyll
+
       - name: Check docs links
         env:
           LITESTAR_DOCS_IGNORE_MISSING_EXAMPLE_OUTPUT: 1

.github/workflows/docs-preview.yml

@@ -44,7 +44,15 @@ jobs:
         with:
           script: |
             const issue_number = process.env.PR_NUMBER
-            const body = "Documentation preview will be available shortly at https://litestar-org.github.io/advanced-alchemy-docs-preview/" + issue_number
+            const previewUrl = `https://litestar-org.github.io/advanced-alchemy-docs-preview/${issue_number}`
+            const body = `## 📚 Documentation Preview
+
+            The documentation preview for this PR is available at:
+
+            **${previewUrl}**
+
+            > [!NOTE]
+            > The preview is updated automatically when changes are pushed to this PR.`
 
             const opts = github.rest.issues.listComments.endpoint.merge({
               owner: context.repo.owner,
@@ -55,7 +63,7 @@ jobs:
             const comments = await github.paginate(opts)
 
             for (const comment of comments) {
-              if (comment.user.id === 41898282 && comment.body === body) {
+              if (comment.user.id === 41898282 && comment.body.includes('Documentation Preview')) {
                 await github.rest.issues.deleteComment({
                   owner: context.repo.owner,
                   repo: context.repo.repo,

.gitignore

@@ -191,3 +191,7 @@ requirements/archive/*
 requirements/*
 !requirements/example-feature
 !requirements/README.md
+
+# Temporary documentation audit files
+REFERENCE_DOCS_*.md
+gif.md

docs/conf.py

@@ -26,6 +26,12 @@
 project = __project__
 copyright = f"{current_year}, Litestar Organization"  # noqa: A001
 release = os.getenv("_ADVANCED-ALCHEMY_DOCS_BUILD_VERSION", __version__.rsplit(".")[0])
+
+# Configure base URL for PR preview deployments
+pr_number = os.getenv("PR_NUMBER")
+if pr_number:
+    html_baseurl = f"https://litestar-org.github.io/advanced-alchemy-docs-preview/{pr_number}/"
+
 suppress_warnings = [
     "autosectionlabel.*",
     "ref.python",  # TODO: remove when https://github.com/sphinx-doc/sphinx/issues/4961 is fixed

docs/getting-started.rst

@@ -4,8 +4,8 @@ Getting Started
 
 Advanced Alchemy is a carefully crafted, thoroughly tested, optimized companion library for :doc:`SQLAlchemy <sqlalchemy:index>`.
 
-It provides :doc:`base classes <reference/base>`, :doc:`mixins <reference/mixins/index>`, :doc:`custom column types <usage/types>`,
-and implementations of the :doc:`repository <usage/repositories>` and :doc:`service layer <usage/services>` patterns
+It provides :doc:`base classes <reference/base>`, :doc:`mixins <reference/mixins/index>`, :doc:`custom column types <usage/types/index>`,
+and implementations of the :doc:`repository <usage/repositories/index>` and :doc:`service layer <usage/services/index>` patterns
 to simplify your database operations.
 
 .. seealso:: It is built on:
@@ -18,11 +18,39 @@ It's designed to work on its own or with your favorite web framework.
 
 We've built extensions for some of the most popular frameworks, so you can get the most out of Advanced Alchemy with minimal effort.
 
-* `Litestar <https://docs.litestar.dev/>`_
-* `FastAPI <https://fastapi.tiangolo.com/>`_
-* `Starlette <https://www.starlette.io/>`_
-* `Flask <https://flask.palletsprojects.com/>`_
-* `Sanic <https://sanicframework.org/>`_
+.. grid:: 1 1 2 2
+    :padding: 0
+    :gutter: 2
+
+    .. grid-item-card:: Litestar
+        :link: https://docs.litestar.dev/
+        :link-type: url
+
+        Async web framework with built-in Advanced Alchemy support
+
+    .. grid-item-card:: FastAPI
+        :link: https://fastapi.tiangolo.com/
+        :link-type: url
+
+        Modern async web framework with automatic API documentation
+
+    .. grid-item-card:: Starlette
+        :link: https://www.starlette.io/
+        :link-type: url
+
+        Lightweight async web framework and toolkit
+
+    .. grid-item-card:: Flask
+        :link: https://flask.palletsprojects.com/
+        :link-type: url
+
+        Lightweight sync web framework
+
+    .. grid-item-card:: Sanic
+        :link: https://sanicframework.org/
+        :link-type: url
+
+        High-performance async web framework
 
 If your framework is not listed, don't worry! Advanced Alchemy is designed to be modular and easily integrated with any Python web framework.
 `Join our Discord <https://discord.gg/dSDXd4mKhp>`_ and we'll help you get started.

docs/index.rst

@@ -41,8 +41,8 @@
     Advanced Alchemy is a carefully crafted, thoroughly tested, optimized companion library for
     :doc:`SQLAlchemy <sqlalchemy:index>`.
 
-It provides :doc:`base classes <reference/base>`, :doc:`mixins <reference/mixins/index>`, :doc:`custom column types <usage/types>`,
-and implementations of the :doc:`repository <usage/repositories>` and :doc:`service layer <usage/services>` patterns
+It provides :doc:`base classes <reference/base>`, :doc:`mixins <reference/mixins/index>`, :doc:`custom column types <usage/types/index>`,
+and implementations of the :doc:`repository <usage/repositories/index>` and :doc:`service layer <usage/services/index>` patterns
 to simplify your database operations.
 
 .. container:: buttons wrap

docs/reference/base.rst

@@ -2,9 +2,85 @@
 base
 ====
 
+.. currentmodule:: advanced_alchemy.base
+
+Base model classes for SQLAlchemy ORM with common patterns and functionality.
+
 .. automodule:: advanced_alchemy.base
-    :members:
-    :imported-members:
-    :undoc-members:
+    :no-members:
+    :no-special-members:
     :show-inheritance:
-    :no-index: advanced_alchemy.base.AdvancedDeclarativeBase.registry advanced_alchemy.base.BasicAttributes.to_dict
+
+UUID Primary Key Models
+------------------------
+
+.. autoclass:: UUIDBase
+   :members:
+   :show-inheritance:
+
+Base model with UUID primary key (UUID v4).
+
+.. autoclass:: UUIDAuditBase
+   :members:
+   :show-inheritance:
+
+Base model with UUID primary key and audit columns (created_at, updated_at).
+
+.. autoclass:: UUIDv6Base
+   :members:
+   :show-inheritance:
+
+Base model with UUID v6 primary key (time-ordered).
+
+.. autoclass:: UUIDv7Base
+   :members:
+   :show-inheritance:
+
+Base model with UUID v7 primary key (time-ordered, improved sorting).
+
+BigInt Primary Key Models
+--------------------------
+
+.. autoclass:: BigIntBase
+   :members:
+   :show-inheritance:
+
+Base model with BigInt auto-incrementing primary key.
+
+.. autoclass:: BigIntAuditBase
+   :members:
+   :show-inheritance:
+
+Base model with BigInt primary key and audit columns (created_at, updated_at).
+
+NanoID Primary Key Models
+--------------------------
+
+.. autoclass:: NanoIDBase
+   :members:
+   :show-inheritance:
+
+Base model with NanoID primary key (requires nanoid extra).
+
+Declarative Base
+----------------
+
+.. autoclass:: AdvancedDeclarativeBase
+   :members:
+   :show-inheritance:
+   :exclude-members: registry
+
+Enhanced declarative base with additional functionality.
+
+.. autoclass:: CommonTableAttributes
+   :members:
+   :show-inheritance:
+
+Common attributes mixed into all base models.
+
+.. autoclass:: BasicAttributes
+   :members:
+   :show-inheritance:
+   :exclude-members: to_dict
+
+Basic attributes for models (id, to_dict).

docs/reference/cli.rst

@@ -0,0 +1,54 @@
+===
+cli
+===
+
+.. currentmodule:: advanced_alchemy.cli
+
+.. automodule:: advanced_alchemy.cli
+    :members:
+    :show-inheritance:
+
+Overview
+--------
+
+The CLI module provides Click-based command groups for database migrations and management.
+Can be used standalone or integrated into framework CLIs (Litestar, FastAPI, Flask).
+
+Functions
+---------
+
+.. autofunction:: get_alchemy_group
+   :no-index:
+
+.. autofunction:: add_migration_commands
+   :no-index:
+
+Usage
+-----
+
+Standalone CLI:
+
+.. code-block:: python
+
+   from advanced_alchemy.cli import get_alchemy_group
+
+   cli = get_alchemy_group()
+
+   if __name__ == "__main__":
+       cli()
+
+Framework Integration:
+
+.. code-block:: python
+
+   from advanced_alchemy.cli import add_migration_commands
+   from click import Group
+
+   app_cli = Group("myapp")
+   add_migration_commands(app_cli)
+
+See Also
+--------
+
+- :doc:`extensions/litestar/cli` - Litestar CLI integration
+- :doc:`../usage/cli/index` - CLI usage guide

docs/reference/index.rst

@@ -20,6 +20,7 @@ Core Components
     types
     exceptions
     utils
+    cli
 
 Repository & Services
 ---------------------