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:
2026-10-17 02:16:44 +05:30
parent 8253c25928
commit 06ffd2febd
149 changed files with 7132 additions and 4594 deletions

View 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)