docs: usage cli tests (#252)

Usage tests for CLI

Author: euri10

docs/examples/usage/usage_cli_1.py

@@ -0,0 +1,32 @@
+from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+__all__ = ("test_single_and_multiple_configs",)
+
+
+def test_single_and_multiple_configs() -> None:
+    # start-example
+    # Single config
+    db_config = AsyncpgConfig(
+        pool_config={"dsn": "postgresql://user:pass@localhost/mydb"},
+        migration_config={"script_location": "migrations", "enabled": True},
+    )
+
+    # Multiple configs
+    configs = [
+        AsyncpgConfig(
+            bind_key="postgres",
+            pool_config={"dsn": "postgresql://..."},
+            migration_config={"script_location": "migrations/postgres"},
+        )
+        # ... more configs
+    ]
+
+    # Callable function
+    def get_configs() -> list[AsyncpgConfig]:
+        return [db_config]
+
+    # end-example
+    assert isinstance(db_config, AsyncpgConfig)
+    assert isinstance(configs, list)
+    assert callable(get_configs)
+    assert get_configs()[0] is db_config

docs/examples/usage/usage_cli_2.py

@@ -0,0 +1,28 @@
+from sqlspec.adapters.asyncmy import AsyncmyConfig
+from sqlspec.adapters.asyncpg import AsyncpgConfig
+
+__all__ = ("test_multi_config",)
+
+
+def test_multi_config() -> None:
+    # start-example
+    configs = [
+        AsyncpgConfig(
+            bind_key="postgres",
+            pool_config={"dsn": "postgresql://..."},
+            migration_config={"script_location": "migrations/postgres", "enabled": True},
+        ),
+        AsyncmyConfig(
+            bind_key="mysql",
+            pool_config={"host": "localhost", "database": "mydb"},
+            migration_config={"script_location": "migrations/mysql", "enabled": True},
+        ),
+        AsyncpgConfig(
+            bind_key="analytics",
+            pool_config={"dsn": "postgresql://analytics/..."},
+            migration_config={"script_location": "migrations/analytics", "enabled": True},
+        ),
+    ]
+    # end-example
+    assert isinstance(configs, list)
+    assert all(hasattr(cfg, "bind_key") for cfg in configs)

docs/usage/cli.rst

@@ -218,32 +218,12 @@ The ``--config`` option accepts a dotted path to either:
 
 Example configuration file (``myapp/config.py``):
 
-.. code-block:: python
-
-   from sqlspec.adapters.asyncpg import AsyncpgConfig
-
-   # Single config
-   db_config = AsyncpgConfig(
-       pool_config={"dsn": "postgresql://user:pass@localhost/mydb"},
-       migration_config={
-           "script_location": "migrations",
-           "enabled": True
-       }
-   )
-
-   # Multiple configs
-   configs = [
-       AsyncpgConfig(
-           bind_key="postgres",
-           pool_config={"dsn": "postgresql://..."},
-           migration_config={"script_location": "migrations/postgres"}
-       ),
-       # ... more configs
-   ]
-
-   # Callable function
-   def get_configs():
-       return [db_config]
+.. literalinclude:: /examples/usage/usage_cli_1.py
+   :language: python
+   :dedent: 0
+   :start-after: # start-example
+   :end-before: # end-example
+   :caption: `configuration loading`
 
 Global Options
 --------------
@@ -769,29 +749,12 @@ them collectively or selectively.
 Scenario: Multiple Databases
 -----------------------------
 
-.. code-block:: python
-
-   # config.py
-   from sqlspec.adapters.asyncpg import AsyncpgConfig
-   from sqlspec.adapters.asyncmy import AsyncmyConfig
-
-   configs = [
-       AsyncpgConfig(
-           bind_key="postgres",
-           pool_config={"dsn": "postgresql://..."},
-           migration_config={"script_location": "migrations/postgres", "enabled": True}
-       ),
-       AsyncmyConfig(
-           bind_key="mysql",
-           pool_config={"host": "localhost", "database": "mydb"},
-           migration_config={"script_location": "migrations/mysql", "enabled": True}
-       ),
-       AsyncpgConfig(
-           bind_key="analytics",
-           pool_config={"dsn": "postgresql://analytics/..."},
-           migration_config={"script_location": "migrations/analytics", "enabled": True}
-       ),
-   ]
+.. literalinclude:: /examples/usage/usage_cli_2.py
+   :language: python
+   :dedent: 0
+   :start-after: # start-example
+   :end-before: # end-example
+   :caption: `multiple databases`
 
 Upgrade All Enabled Configs
 ----------------------------