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:
@@ -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)
|
||||
Reference in New Issue
Block a user