docs(wiki): align wiki structure with Aetoskia AGENTS.md guidelines

- Renamed `02_architecture.md` to `02_components.md` to match the standard component page naming convention.
- Updated `docs/mkdocs.wiki.yml` to reflect renamed pages and fix navigation label acronym casing (GSDFC, MCP, MkDocs).
- Updated `index.md` to include the mandatory doc model blockquote, standardize section headers with emojis, and accurately map the `Documentation Structure` table to the navigation menu.
- Standardized all wiki pages (`01_overview.md`, `02_components.md`, `03_conventions.md`, `04_iterative_workflow.md`, and `05_development/*`) by:
  - Adding horizontal rules (`---`) between major sections.
  - Applying emoji-prefixed H2 headings for recognizable section types.
  - Appending `## Related` or `## ➡️ Read Next` footers with standard relative cross-links.
  - Adjusting H1 headers to match guide anatomy (e.g., `# Library Overview` on the overview page).
This commit is contained in:
2026-09-14 23:30:45 +05:30
parent c0d8a252ff
commit 4b0fdfaf85
11 changed files with 194 additions and 67 deletions

View File

@@ -5,7 +5,9 @@ in the `docforge/__init__.py` package docstring. It describes how to write
docstrings that render correctly in MkDocs and stay machine-parseable by
doc-forge, MkDocs, and MCP clients.
## Overview
---
## 🧭 Overview
- Docstrings are the single source of truth.
- `doc-forge` compiles docstrings but never rewrites them.
@@ -13,7 +15,9 @@ doc-forge, MkDocs, and MCP clients.
- Type hints live in signatures; prose entries repeat the type in
parentheses and must match the signature.
## Module docstrings
---
## 📦 Module docstrings
Modules use Markdown headings and `---` separators.
@@ -23,7 +27,9 @@ Recommended sections:
- `# Examples` — a representative usage snippet
- `# Notes` — guarantees, lifecycle, and thread-safety notes
## Class docstrings
---
## 📦 Class docstrings
Recommended sections, in order:
@@ -32,7 +38,9 @@ Recommended sections, in order:
- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle**
- `Example:` — indented `python` code block
## Function and method docstrings
---
## 📦 Function and method docstrings
Recommended section order:
@@ -53,12 +61,16 @@ Formatting rules:
- Fenced `python` blocks are allowed inside `Example:` sections, indented
four spaces.
## Property docstrings
---
## 📦 Property docstrings
Properties document their return values with a `Returns:` section and, when
meaningful, an `Example:`.
## Example
---
## 🚀 Example
```python
def process(foo: Foo, multiplier: int) -> int:
@@ -90,13 +102,17 @@ def process(foo: Foo, multiplier: int) -> int:
"""
```
## Keeping stubs in sync
---
## 🔄 Keeping stubs in sync
Every `.py` module ships a matching `.pyi` stub. When a signature or a public
symbol changes, update both files. Signature annotations in the stub must
match the implementation.
## Enforcement
---
## 🛡️ Enforcement
`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:`
sections match function signatures, including types.
@@ -105,4 +121,9 @@ sections match function signatures, including types.
- `skip-checking-raises = true``Raises:` sections are descriptive and are
not required to map to literal `raise` statements.
- `check-class-attributes = false``Attributes:` sections document instance
attributes without class-level annotations.
attributes without class-level annotations.
---
## Related
- [02 Quality Gates](02_quality_gates.md) · [04 MCP Guide](04_mcp_guide.md)