chore(release): 0.0.7
Squash-merge lib-standardisation: adopt repo standards across packaging, tooling, docs, and CI. - standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint) - add py.typed marker, modernize type hints and Google-style docstrings - nest generated docs under docs/lib and docs/mcp; add hand-written wiki - adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate) - promote generated CHANGELOG.md; bump version to 0.0.7
This commit is contained in:
129
docs/wiki/05_development/03_gsdfc_guide.md
Normal file
129
docs/wiki/05_development/03_gsdfc_guide.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# GSDFC Docstring Guide
|
||||
|
||||
This page is the practical companion to the authoritative GSDFC specification
|
||||
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
|
||||
|
||||
- Docstrings are the single source of truth.
|
||||
- `doc-forge` compiles docstrings but never rewrites them.
|
||||
- Every public symbol should have a complete, accurate docstring.
|
||||
- Type hints live in signatures; prose entries repeat the type in
|
||||
parentheses and must match the signature.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Module docstrings
|
||||
|
||||
Modules use Markdown headings and `---` separators.
|
||||
|
||||
Recommended sections:
|
||||
|
||||
- `# Summary` — what the subsystem does
|
||||
- `# Examples` — a representative usage snippet
|
||||
- `# Notes` — guarantees, lifecycle, and thread-safety notes
|
||||
|
||||
---
|
||||
|
||||
## 📦 Class docstrings
|
||||
|
||||
Recommended sections, in order:
|
||||
|
||||
- summary line describing responsibility
|
||||
- `Attributes:` — instance attributes with `name (Type):` entries
|
||||
- `Notes:` — grouped subsections such as **Guarantees**, **Lifecycle**
|
||||
- `Example:` — indented `python` code block
|
||||
|
||||
---
|
||||
|
||||
## 📦 Function and method docstrings
|
||||
|
||||
Recommended section order:
|
||||
|
||||
1. `Args:`
|
||||
2. `Returns:`
|
||||
3. `Raises:`
|
||||
4. `Yields:`
|
||||
5. `Notes:`
|
||||
6. `Example:`
|
||||
|
||||
Formatting rules:
|
||||
|
||||
- `Args:` entries are `name (Type):` followed by an indented description.
|
||||
- `Returns:` entries are `Type:` followed by an indented description.
|
||||
- `Raises:` entries are `ExceptionType:` followed by an indented condition.
|
||||
- `Yields:` replaces `Returns:` for generators.
|
||||
- Summaries are written in the imperative mood.
|
||||
- Fenced `python` blocks are allowed inside `Example:` sections, indented
|
||||
four spaces.
|
||||
|
||||
---
|
||||
|
||||
## 📦 Property docstrings
|
||||
|
||||
Properties document their return values with a `Returns:` section and, when
|
||||
meaningful, an `Example:`.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Example
|
||||
|
||||
```python
|
||||
def process(foo: Foo, multiplier: int) -> int:
|
||||
"""Process a Foo instance.
|
||||
|
||||
Args:
|
||||
foo (Foo):
|
||||
Foo instance to process.
|
||||
|
||||
multiplier (int):
|
||||
Value used to scale foo.
|
||||
|
||||
Returns:
|
||||
int:
|
||||
Processed result.
|
||||
|
||||
Raises:
|
||||
ValueError:
|
||||
If multiplier is negative.
|
||||
|
||||
Example:
|
||||
Process foo:
|
||||
|
||||
```python
|
||||
foo = Foo("example", value=10)
|
||||
result = process(foo, multiplier=2)
|
||||
print(result)
|
||||
```
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 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
|
||||
|
||||
`pydoclint` (Google style) runs in CI and verifies that `Args:`/`Returns:`
|
||||
sections match function signatures, including types.
|
||||
|
||||
- `allow-init-docstring = true` — `__init__` docstrings are allowed.
|
||||
- `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.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
- [02 – Quality Gates](02_quality_gates.md) · [04 – MCP Guide](04_mcp_guide.md)
|
||||
Reference in New Issue
Block a user