docs: add Diagram specification and update how-to guide

New documentation:
- Add reference/specs/diagram.md with complete API documentation
- Document direction parameter, Mermaid output, and schema grouping

Updates:
- Add Diagram to mkdocs.yaml navigation
- Add Diagram to specs index
- Update read-diagrams.ipynb with new features:
  - Layout direction examples
  - Mermaid output examples
  - Schema grouping examples

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: dimitri-yatsenko

mkdocs.yaml

@@ -102,6 +102,7 @@ nav:
               - Semantic Matching: reference/specs/semantic-matching.md
               - Primary Keys: reference/specs/primary-keys.md
               - Fetch API: reference/specs/fetch-api.md
+              - Diagram: reference/specs/diagram.md
           - Type System:
               - Types: reference/specs/type-system.md
               - Codec API: reference/specs/codec-api.md

src/how-to/read-diagrams.ipynb

@@ -1280,22 +1280,61 @@
    "cell_type": "markdown",
    "id": "cell-ops-ref",
    "metadata": {},
-   "source": [
-    "**Operation Reference:**\n",
-    "\n",
-    "| Operation | Meaning |\n",
-    "|-----------|--------|\n",
-    "| `dj.Diagram(schema)` | Entire schema |\n",
-    "| `dj.Diagram(Table) - N` | Table + N levels upstream |\n",
-    "| `dj.Diagram(Table) + N` | Table + N levels downstream |\n",
-    "| `D1 + D2` | Union of two diagrams |\n",
-    "| `D1 * D2` | Intersection (common nodes) |\n",
-    "\n",
-    "**Finding paths:** Use intersection to find connection paths:\n",
-    "```python\n",
-    "(dj.Diagram(upstream) + 100) * (dj.Diagram(downstream) - 100)\n",
-    "```"
-   ]
+   "source": "**Operation Reference:**\n\n| Operation | Meaning |\n|-----------|--------|\n| `dj.Diagram(schema)` | Entire schema |\n| `dj.Diagram(Table) - N` | Table + N levels upstream |\n| `dj.Diagram(Table) + N` | Table + N levels downstream |\n| `D1 + D2` | Union of two diagrams |\n| `D1 * D2` | Intersection (common nodes) |\n\n**Finding paths:** Use intersection to find connection paths:\n```python\n(dj.Diagram(upstream) + 100) * (dj.Diagram(downstream) - 100)\n```"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2lmw6tar3w8",
+   "source": "## Layout Direction\n\nControl the flow direction of diagrams via configuration:\n\n| Direction | Description |\n|-----------|-------------|\n| `\"TB\"` | Top to bottom (default) |\n| `\"LR\"` | Left to right |\n\n```python\n# Set globally\ndj.config.display.diagram_direction = \"LR\"\n\n# Or override temporarily\nwith dj.config.override(display__diagram_direction=\"LR\"):\n    dj.Diagram(schema).draw()\n```",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "7nsvct1qdqu",
+   "source": "# Horizontal layout using config override\nwith dj.config.override(display__diagram_direction=\"LR\"):\n    display(dj.Diagram(schema))",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ogpr8cqsife",
+   "source": "## Mermaid Output\n\nGenerate [Mermaid](https://mermaid.js.org/) syntax for embedding diagrams in Markdown documentation, GitHub, or web pages:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "vlq9xju4bm",
+   "source": "# Generate Mermaid syntax\nprint((dj.Diagram(Subject) + 2).make_mermaid())",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "jsi0zuoxzvn",
+   "source": "Copy this output into any Mermaid-compatible viewer (GitHub Markdown, MkDocs with mermaid plugin, https://mermaid.live) to render the diagram.\n\n**Saving to file:**\n```python\ndj.Diagram(schema).save(\"pipeline.mmd\")  # .mmd or .mermaid extension\n```",
+   "metadata": {}
+  },
+  {
+   "cell_type": "markdown",
+   "id": "pqet0vo8pwp",
+   "source": "## Schema Grouping\n\nWhen visualizing multi-schema pipelines, group tables by their database schema for clarity:",
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "id": "9dx25khprlm",
+   "source": "# Group tables by schema (shows dashed boxes around each schema)\ndj.Diagram(schema).draw(group_by_schema=True)",
+   "metadata": {},
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cyv4xl01iow",
+   "source": "**When to use schema grouping:**\n- Visualizing pipelines spanning multiple schemas\n- Understanding which tables belong to which database\n- Documentation for multi-schema architectures\n\n**Saving with grouping:**\n```python\ndj.Diagram(schema1) + dj.Diagram(schema2)\ndiag.save(\"multi_schema.svg\", group_by_schema=True)\n```",
+   "metadata": {}
   },
   {
    "cell_type": "markdown",
@@ -1347,24 +1386,7 @@
    "cell_type": "markdown",
    "id": "cell-summary-md",
    "metadata": {},
-   "source": [
-    "## Summary\n",
-    "\n",
-    "| Visual | Meaning |\n",
-    "|--------|--------|\n",
-    "| **Thick solid** | One-to-one extension |\n",
-    "| **Thin solid** | One-to-many containment |\n",
-    "| **Dashed** | Reference (independent identity) |\n",
-    "| **Underlined** | Introduces new dimension |\n",
-    "| **Orange dots** | Renamed FK via `.proj()` |\n",
-    "| **Colors** | Green=Manual, Gray=Lookup, Red=Computed, Blue=Imported |\n",
-    "\n",
-    "## Related\n",
-    "\n",
-    "- [Entity Integrity: Dimensions](../explanation/entity-integrity.md#schema-dimensions)\n",
-    "- [Semantic Matching](../reference/specs/semantic-matching.md)\n",
-    "- [Schema Design Tutorial](../tutorials/basics/02-schema-design.ipynb)"
-   ]
+   "source": "## Summary\n\n| Visual | Meaning |\n|--------|--------|\n| **Thick solid** | One-to-one extension |\n| **Thin solid** | One-to-many containment |\n| **Dashed** | Reference (independent identity) |\n| **Underlined** | Introduces new dimension |\n| **Orange dots** | Renamed FK via `.proj()` |\n| **Colors** | Green=Manual, Gray=Lookup, Red=Computed, Blue=Imported |\n\n| Feature | Method |\n|---------|--------|\n| Layout direction | `dj.config.display.diagram_direction` |\n| Mermaid output | `.make_mermaid()` |\n| Schema grouping | `.draw(group_by_schema=True)` |\n\n## Related\n\n- [Diagram Specification](../reference/specs/diagram.md)\n- [Entity Integrity: Dimensions](../explanation/entity-integrity.md#schema-dimensions)\n- [Semantic Matching](../reference/specs/semantic-matching.md)\n- [Schema Design Tutorial](../tutorials/basics/02-schema-design.ipynb)"
   },
   {
    "cell_type": "code",
@@ -1405,4 +1427,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}