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,59 @@
# MkDocs Configuration Model
Each documentation kind (lib, api, wiki) is built by its own MkDocs site. A
repo that documents kind `{kind}` carries a config at `docs/mkdocs.{kind}.yml`
that sets `docs_dir` to the kind's source directory and `site_dir` to
`../site/{kind}`.
---
## 📄 File wins
`docs/mkdocs.{kind}.yml` is a repo-owned file, not a build byproduct:
- **Absent** — `doc-forge build --{kind}` materializes a copy from the
packaged templates (see below) and then builds `site/{kind}`.
- **Present** — the build uses the file verbatim. Edits to the theme, palette,
plugins, markdown extensions, nav, or `site_dir` are respected as-is.
- **`--refresh`** — force-regenerates the file from the templates,
replacing any local changes.
Because a present file is never rewritten, rerunning a build is a no-op for
versioned configs: the working tree stays clean.
---
## 🧩 Templates
The built-in defaults live in `docforge/templates/`:
| File | Role |
|-----------------------|-----------------------------------------------|
| `mkdocs.common.yml` | Shared theme + markdown extensions |
| `mkdocs.lib.yml` | `mkdocstrings` handler for library reference |
| `mkdocs.api.yml` | Swagger/OpenAPI plugins and API-side features |
| `mkdocs.wiki.yml` | Wiki look: horizontal `navigation.tabs` header, blue grey/teal palette, Roboto |
A per-kind config is generated by deep-merging the common template with the
kind fragment, then filling in generation-time values (`site_name`,
`docs_dir`, `site_dir`, `nav`, API `site_description`/`site_author`, and the
theme `icon` from `docforge.nav.yml`). Pass `--template <path>` to replace the
built-in templates entirely.
---
## 🏗️ Supported layouts
- **Per-kind config** — the standard layout; each kind builds to
`site/{kind}` and is served under `/<repo>/{kind}/`.
- **Legacy root config** — a repo with a single kind may instead author root
`mkdocs.yml` (for example mongo-ops, whose wiki uses `docs_dir: docs/wiki`).
doc-forge never reads or writes root `mkdocs.yml`; the docs service maps the
kind to the root `site/` dir in this case.
Commit `docs/mkdocs.{kind}.yml` so served docs are reproducible from source.
---
## Related
- [04 – MCP Guide](04_mcp_guide.md)