docs: adds snippets extension to the project

Author: matheusvnm

.github/workflows/test-docs.yml

@@ -3,75 +3,90 @@ name: Test Documentation
 on:
   push:
     paths:
-      - 'docs/src/snippets/**/*.py'
-      - 'docs/src/**/*.md'
+      - 'docs/snippets/**/*.py'
+      - 'docs/markdown/**/*.md'
+      - 'tests/unit/docs/**/*.py'
+      - 'tests/integration/docs/**/*.py'
       - '.github/workflows/test-docs.yml'
   pull_request:
     paths:
-      - 'docs/src/snippets/**/*.py'
-      - 'docs/src/**/*.md'
+      - 'docs/snippets/**/*.py'
+      - 'docs/markdown/**/*.md'
+      - 'tests/unit/docs/**/*.py'
+      - 'tests/integration/docs/**/*.py'
       - '.github/workflows/test-docs.yml'
 
+env:
+  UV_LINK_MODE: "copy"
+  UV_PYTHON_VERSION: "3.12"
+
 jobs:
-  validate-snippets:
-    name: Validate Code Snippets
+  unit-tests:
+    name: Documentation Unit Tests
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
+      - name: Setup just command
+        uses: extractions/setup-just@v3
         with:
-          python-version: '3.12'
+          just-version: '1.43.0'
+
+      - name: Install uv command
+        uses: astral-sh/setup-uv@v7
 
       - name: Install dependencies
-        run: |
-          pip install -e ".[dev]"
+        run: just init $UV_PYTHON_VERSION
 
-      - name: Check Python syntax
-        run: |
-          echo "Checking Python syntax in docs/src/snippets/"
-          python -m py_compile docs/src/snippets/**/*.py
-          echo "All snippets have valid Python syntax"
+      - name: Run snippet syntax tests
+        run: uv run pytest tests/unit/docs/test_snippets_syntax.py -v
 
-      - name: Run snippet imports
-        run: |
-          echo "Verifying all snippets can be imported"
-          python << 'EOF'
-          import importlib.util
-          import sys
-          from pathlib import Path
-
-          snippets_dir = Path("docs/src/snippets")
-          errors = []
-
-          for py_file in snippets_dir.rglob("*.py"):
-              if py_file.name == "__init__.py":
-                  continue
-
-              module_name = py_file.stem
-              spec = importlib.util.spec_from_file_location(module_name, py_file)
-
-              if spec and spec.loader:
-                  try:
-                      module = importlib.util.module_from_spec(spec)
-                      # Don't execute, just verify it can be loaded
-                      print(f"✓ {py_file.relative_to(snippets_dir)}")
-                  except Exception as e:
-                      errors.append(f"✗ {py_file.relative_to(snippets_dir)}: {e}")
-
-          if errors:
-              print("\nErrors found:")
-              for error in errors:
-                  print(error)
-              sys.exit(1)
-          else:
-              print(f"\nAll {len(list(snippets_dir.rglob('*.py')))} snippets validated successfully")
-          EOF
+      - name: Run snippet marker tests
+        run: uv run pytest tests/unit/docs/test_snippets_markers.py -v
+
+      - name: Run snippet import tests
+        run: uv run pytest tests/unit/docs/test_snippets_imports.py -v
+
+      - name: Run all unit tests
+        run: uv run pytest tests/unit/docs/ -v
+
+  integration-tests:
+    name: Documentation Integration Tests
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    services:
+      pubsub:
+        image: gcr.io/google.com/cloudsdktool/google-cloud-cli:emulators
+        ports:
+          - 8085:8085
+        options: >-
+          --health-cmd "curl -f http://localhost:8085 || exit 1"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      PUBSUB_EMULATOR_HOST: localhost:8085
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup just command
+        uses: extractions/setup-just@v3
+        with:
+          just-version: '1.43.0'
+
+      - name: Install uv command
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: just init $UV_PYTHON_VERSION
+
+      - name: Run integration tests
+        run: uv run pytest tests/integration/docs/ -v --timeout=60
 
   build-docs:
     name: Build Documentation
     runs-on: ubuntu-latest
+    needs: unit-tests
     steps:
       - uses: actions/checkout@v5
 
@@ -87,49 +102,5 @@ jobs:
         run: |
           cd docs
           zensical build --clean
-          echo "Documentation built successfully"
-
-      - name: Check for broken internal links
-        run: |
-          echo "Checking for broken links in documentation"
-          python << 'EOF'
-          import re
-          from pathlib import Path
-
-          docs_dir = Path("docs/src")
-          errors = []
-
-          # Pattern to match markdown links
-          link_pattern = re.compile(r'\[([^\]]+)\]\(([^)]+)\)')
-
-          for md_file in docs_dir.rglob("*.md"):
-              content = md_file.read_text()
-
-              for match in link_pattern.finditer(content):
-                  link_text, link_url = match.groups()
-
-                  # Skip external links
-                  if link_url.startswith(('http://', 'https://', '#', 'mailto:')):
-                      continue
-
-                  # Resolve relative path
-                  if link_url.startswith('../'):
-                      target = (md_file.parent / link_url).resolve()
-                  else:
-                      target = (md_file.parent / link_url).resolve()
-
-                  # Remove anchor if present
-                  target_path = str(target).split('#')[0]
-
-                  if not Path(target_path).exists():
-                      errors.append(f"{md_file.relative_to(docs_dir)}: broken link '{link_url}'")
-
-          if errors:
-              print("Broken links found:")
-              for error in errors:
-                  print(f"  ✗ {error}")
-              # Warning only, don't fail the build
-              print(f"\nFound {len(errors)} broken links (warning only)")
-          else:
-              print("No broken links found")
-          EOF
+          echo "Documentation built successfully with snippet inclusion"
+           echo "All snippet references validated"

docs/markdown/tutorial/user-guide/cli.md

@@ -38,16 +38,7 @@ The primary command is `run`, which takes one required argument: the path to you
 **Example application (`my_project/main.py`):**
 
 ```python
-from fastpubsub import FastPubSub, PubSubBroker
-
-broker = PubSubBroker("your-project-id")
-app = FastPubSub(broker)
-
-@broker.subscriber("process-orders", topic_name="orders", subscription_name="orders-sub")
-async def handle_orders(message): ...
-
-@broker.subscriber("send-notifications", topic_name="notifications", subscription_name="notifications-sub")
-async def handle_notifications(message): ...
+--8<-- "basic_usage/e8_01_cli_example.py:cli_example_full"
 ```
 
 **Run with default settings:**

docs/markdown/tutorial/user-guide/deployment.md

@@ -219,15 +219,7 @@ sudo systemctl status fastpubsub
 Never hardcode production values:
 
 ```python
-import os
-from fastpubsub import FastPubSub, PubSubBroker
-
-PROJECT_ID = os.environ.get("GCP_PROJECT_ID")
-if not PROJECT_ID:
-    raise RuntimeError("GCP_PROJECT_ID environment variable not set.")
-
-broker = PubSubBroker(project_id=PROJECT_ID)
-app = FastPubSub(broker)
+--8<-- "basic_usage/e8_02_deployment_config.py:deployment_config_full"
 ```
 
 In Kubernetes, inject via `ConfigMaps` or `Secrets`.

docs/markdown/tutorial/user-guide/first-steps.md

@@ -28,10 +28,7 @@ FastPubSub has two main classes that form the backbone of every application:
 All Pub/Sub configuration attaches to the broker. The `FastPubSub` object takes a `PubSubBroker` instance as an argument. This separation lets you use all FastAPI features (middlewares, lifespan) with the application while integrating with the broker.
 
 ```python
-from fastpubsub import FastPubSub, PubSubBroker
-
-broker = PubSubBroker(project_id="your-project-id")
-app = FastPubSub(broker)
+--8<-- "basic_usage/e0_01_first_steps.py:broker_app"
 ```
 
 ---
@@ -41,36 +38,7 @@ app = FastPubSub(broker)
 Create a file named `basic.py`:
 
 ```python
-from pydantic import BaseModel, Field
-from fastpubsub import FastPubSub, PubSubBroker, Message
-from fastpubsub.logger import logger
-
-
-class Address(BaseModel):
-    street: str = Field(..., examples=["5th Avenue"])
-    number: str = Field(..., examples=["1548"])
-
-
-broker = PubSubBroker(project_id="your-project-id")
-app = FastPubSub(broker)
-
-
-@app.post("/addresses/")
-async def create_address(address: Address):
-    logger.info(f"Address received: {address}")
-    await broker.publish(topic_name="address-events", data=address)
-    return {"message": "Address published"}
-
-
-@broker.subscriber(
-    alias="address-handler",
-    topic_name="address-events",
-    subscription_name="address-events-subscription",
-)
-async def handle_message(message: Message):
-    logger.info(f"The message {message.id} arrived.")
-    address = Address.model_validate_json(message.data)
-    logger.info(f"Address: {address}")
+--8<-- "basic_usage/e0_01_first_steps.py:first_steps_full"
 ```
 
 This application:
@@ -163,10 +131,6 @@ Notice how the logs include context like `message_id`, `topic_name`, and the han
 
 ### The Broker
 
-```python
-broker = PubSubBroker(project_id="your-project-id")
-```
-
 The broker manages all Pub/Sub connections. It handles:
 
 - Creating topics and subscriptions (when `autocreate=True`)
@@ -175,10 +139,6 @@ The broker manages all Pub/Sub connections. It handles:
 
 ### The Application
 
-```python
-app = FastPubSub(broker)
-```
-
 The application is a FastAPI instance with Pub/Sub integration. You can use all FastAPI features like:
 
 - Path operations (`@app.get()`, `@app.post()`)
@@ -189,13 +149,7 @@ The application is a FastAPI instance with Pub/Sub integration. You can use all
 ### The Subscriber
 
 ```python
-@broker.subscriber(
-    alias="address-handler",
-    topic_name="address-events",
-    subscription_name="address-events-subscription",
-)
-async def handle_message(message: Message):
-    ...
+--8<-- "basic_usage/e0_01_first_steps.py:subscriber"
 ```
 
 The `@broker.subscriber` decorator registers an async function as a message handler. Key parameters:
@@ -211,7 +165,7 @@ By default, `autocreate=True`, so FastPubSub creates the topic and subscription
 ### Publishing
 
 ```python
-await broker.publish(topic_name="address-events", data=address)
+--8<-- "basic_usage/e0_01_first_steps.py:rest_endpoint"
 ```
 
 The broker's `publish` method sends messages to a topic. It automatically serializes:

docs/markdown/tutorial/user-guide/lifecycle.md

@@ -54,16 +54,7 @@ Sometimes, you receive a message that you cannot process, but you don't want it
 
 
 ```python
-from fastpubsub.exceptions import Drop
-
-@broker.subscriber(...)
-async def handle_events(message: Message):
-    event_attributes = message.attributes
-    if event_attributes.get("schema_version") == "v1":
-        # We no longer support v1 events
-        raise Drop("Schema version v1 is deprecated.")
-
-    # Process v2+ events...
+--8<-- "basic_usage/e7_01_lifecycle_drop.py:drop_handler"
 ```
 
 
@@ -76,18 +67,7 @@ For temporary, recoverable errors (e.g., a database is temporarily unavailable,
 
 
 ```python
-from fastpubsub.exceptions import Retry
-import httpx
-
-@broker.subscriber(...)
-async def handle_order(message: Message):
-    order_id = json.loads(message.data)["order_id"]
-    try:
-        async with httpx.AsyncClient() as client:
-            await client.post(f"https://downstream.service/process/{order_id}")
-    except httpx.TimeoutException:
-        # Service is slow, retry later
-        raise Retry("Downstream service timed out.")
+--8<-- "basic_usage/e7_02_lifecycle_retry.py:retry_handler"
 ```
 
 !!! tip "Exponential Backoff"
@@ -103,12 +83,7 @@ Any exception that is not `Drop` or `Retry` is considered an unhandled unexpecte
 
 
 ```python
-@broker.subscriber(...)
-async def handle_event(message: Message):
-    # If this raises ValueError, KeyError, etc.
-    # the message is nacked and redelivered
-    data = json.loads(message.data)
-    await process(data)
+--8<-- "basic_usage/e7_03_lifecycle_unhandled.py:unhandled_handler"
 ```
 
 ---