feat: add documentation cursor rule for docs/**/*.md

Author: HosseinNejatiJavaremi

.cursor/rules/documentation.mdc

@@ -0,0 +1,94 @@
+---
+description: Documentation standards for ArchiPy MkDocs pages
+globs: docs/**/*.md
+alwaysApply: false
+---
+
+# Documentation Standards
+
+## File Naming
+
+- All filenames must be lowercase `snake_case` (e.g., `config_management.md`, `bdd_testing.md`).
+- Every directory must have an `index.md` overview file.
+- Adapter and helper filenames must match the Python module name exactly (e.g., `scylladb.md`, `metaclasses.md`).
+
+## Page Structure
+
+Every page must open with YAML frontmatter:
+
+```yaml
+---
+title: <Short Human-Readable Title>
+description: <One-sentence description of the page>
+---
+```
+
+Heading hierarchy: `#` H1 (matches `title`) → `##` major sections → `###` subsections. Do not skip levels.
+
+### Adapter Example Pages — required sections (in order)
+
+1. `## Installation` — single `bash` block: `uv add "archipy[extra]"`
+2. `## Configuration` → `### Environment Variables` (bash block) + `### Direct Configuration` (python block)
+3. `## Basic Usage` — complete, runnable Python snippets
+4. `## Advanced <Feature>` — deeper patterns (add as needed)
+5. `## See Also` — 4–6 relative links to related docs
+
+### API Reference Pages — required sections
+
+H1 + intro prose → `## Ports`, `## Adapters`, `## Mocks`, each with an mkdocstrings directive:
+
+```markdown
+::: archipy.adapters.<name>.ports
+    options:
+      show_root_toc_entry: false
+      heading_level: 3
+```
+
+## Code Example Standards
+
+- Always use `import logging` and `logger = logging.getLogger(__name__)`. Never use `print()`.
+- Full Python 3.14+ type hints: `list[str]`, `dict[str, Any]`, `X | Y` — never `Optional[X]` or `Union[X, Y]`.
+- Google-style docstrings on every defined function or class.
+- Catch specific exception types only; always chain with `raise ... from e`.
+- Every fenced code block must have a language tag (`python` or `bash`).
+
+```python
+# ✅ GOOD
+import logging
+
+logger = logging.getLogger(__name__)
+
+def get_item(key: str) -> str | None:
+    """Retrieve an item by key.
+
+    Args:
+        key: The cache key to look up.
+
+    Returns:
+        The cached value, or None if not found.
+
+    Raises:
+        CacheError: If the cache is unreachable.
+    """
+    try:
+        return cache.get(key)
+    except ConnectionError as e:
+        raise CacheError("Cache unreachable") from e
+```
+
+## Writing Style
+
+- **Admonitions**: use `!!! note`, `!!! tip`, `!!! warning`. `note` supports an optional inline title: `!!! note "Title"`.
+- **Cross-links**: always relative paths (e.g., `[Error Handling](../error_handling.md)`).
+- **Emphasis**: bold (`**term**`) for key terms on first mention. No emoji outside `index.md` and overview pages.
+- **Tables**: use for structured comparison data (extras matrix, config options).
+- **`## See Also`**: end every adapter example page with this section linking to error handling, config, BDD testing, related helpers, and the corresponding API reference page.
+
+## New Adapter Checklist
+
+When documenting a new adapter, create **both** files:
+
+- `docs/examples/adapters/<name>.md` — example guide with all 5 required sections
+- `docs/api_reference/adapters/<name>.md` — API reference with mkdocstrings directives
+
+Then add both entries under the appropriate `nav:` keys in `mkdocs.yml`.