hf-doc-builder-architect
Architect, compile, and verify multi-package documentation using zero-dependency mock virtualization, deterministic AST anchor graphs, and unified MDX transpilation. Do not use for generic prose editing or static site hosting.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- hf-doc-builder-architect
- description
- Architect, compile, and verify multi-package documentation using zero-dependency mock virtualization, deterministic AST anchor graphs, and unified MDX transpilation. Do not use for generic prose editing or static site hosting.
02 资源文件 4
- 参考文档CARD.md3.3 KB
- 参考文档config.default.yaml516 B
- 脚本scripts/__init__.py37 B
- 脚本scripts/doc_builder_engine.py1.6 KB
03 SKILL.md 正文
HF Doc Builder Architect: Multi-Package Documentation Engineering
hf-doc-builder-architect is the authoritative documentation compilation and verification engine for Brain Harness, distilled from Hugging Face doc-builder (hf-doc-builder). It provides zero-dependency mock virtualization for Python AST introspection, deterministic Markdown anchor graph verification, multi-dialect MDX transpilation, and heading-bounded semantic chunking.
See CARD.md for the companion summary card, 5-stage progression matrix, and invariants checklist. Consult config.default.yaml for baseline operational budgets and zero-fork configuration. Refer to developer-docs-architect for Diataxis documentation taxonomy.
The 5-Stage Shu-Ha-Ri Operational Pipeline
[1. Docstring & AST Extraction] ──► [2. Zero-Dep Mock Virtualization] ──► [3. Multi-Dialect MDX Compilation]
│
▼
[5. Hierarchical Chunk & Vector Index] ◄── [4. Anchor Graph & TOC Verification] ◄──────┘
1. Stage 1 (Shu): Docstring & AST Extraction
Extract structured signatures, type annotations, and docstrings from Python modules:
- Object Resolution:
- Locate target objects (classes, methods, functions) in the specified package hierarchy.
- Detect docstring syntax: Google style, NumPy style, or reStructuredText (Sphinx).
- Signature Normalization:
- Parse
inspect.signatureor AST argument nodes, preserving default values and type annotations. - Separate positional-only, keyword-only,
*args, and**kwargs.
- Parse
- Structured Parameter Table:
- Map parameters to typed definitions with extracted doc descriptions.
Completion criterion: Structured
AutodocSignaturegenerated with valid parameter list and return type.
2. Stage 2 (Shu): Zero-Dependency Mock Virtualization
Introspect deep learning and native modules without hardware or dependency overhead:
- Meta-Path Import Interception:
- Deploy
MockFinderintosys.meta_pathto intercept uninstalled third-party modules (e.g.,torch,tensorflow,jax,flax).
- Deploy
- Metaclass Inheritance Shielding:
- When documented classes subclass external types (
class Model(nn.Module)), dynamically synthesize proxy base classes so module loading never raisesTypeError.
- When documented classes subclass external types (
- Distribution & Version Spoofing:
- Intercept
importlib.metadata.versioncalls to return mock SemVer versions satisfying runtime version gates.
- Intercept
Completion criterion: Target Python package imports successfully and inspects cleanly in an unprovisioned environment.
3. Stage 3 (Ha): Multi-Dialect MDX Compilation
Transpile disparate documentation dialects into unified, reactive Svelte MDX:
- Dialect Normalization:
- Convert standard Markdown, reStructuredText (Sphinx directives), and Jupyter Notebooks (
.ipynb) into unified MDX.
- Convert standard Markdown, reStructuredText (Sphinx directives), and Jupyter Notebooks (
- Component Tag Injection:
- Translate doc callouts into reactive component tags (
<Tip>,<Warning>,<FrameworkContent>,<InferenceSnippet>).
- Translate doc callouts into reactive component tags (
- Codeblock Formatting:
- Lint and format Python example blocks using Ruff, stripping internal test harnesses or doctest artifacts.
Completion criterion: Unified
.mdxoutput generated with valid component tags and formatted examples.
4. Stage 4 (Ha): Anchor Graph & TOC Verification
Ensure 100% link integrity and navigation tree completeness:
- Code & Comment Masking:
- Strip code fences (```) and inline backticks to prevent false-positive link matches.
- Anchor Index Construction:
- Extract heading slugs (
#heading-title), HTML IDs (<a id="...">), and autodoc anchors into an in-memory graph.
- Extract heading slugs (
- Extensionless Route Resolution:
- Resolve relative links written without extensions (
./pipeline->./pipeline.mdor./pipeline.mdx).
- Resolve relative links written without extensions (
- Table of Contents Integrity:
- Audit
_toctree.ymlagainst filesystem to detect dead links and orphaned pages.
- Audit
Completion criterion: 0 broken relative links, 0 dead anchors, and complete TOC coverage.
5. Stage 5 (Ri): Hierarchical Chunking & Semantic Search
Partition documentation for hybrid vector and full-text retrieval:
- Heading Tree Partitioning:
- Split documentation along
H1->H2->H3boundaries rather than arbitrary token counts.
- Split documentation along
- Breadcrumb Hierarchy Preservation:
- Attach the full navigation path (
Library > Guide > Section) to each chunk payload.
- Attach the full navigation path (
- Dense & Sparse Index Payload:
- Emit structured chunks with character and token bounds, ready for Meilisearch full-text or embedding ingestion.
Completion criterion: Structured array of
DocChunknodes emitted with hierarchical breadcrumbs and token estimates.
The Three Foundational Pillars
1. Zero-Dependency Mock Virtualization
Never fail AST documentation introspection due to missing CUDA or heavy frameworks. Use in-process meta-path interception to virtualize dependencies dynamically.
2. Deterministic Anchor Graph Integrity
Never ship broken relative links or dead heading anchors. Lexically mask codeblocks and verify the complete anchor graph across files and extensionless routes.
3. Unified Transpilation & Semantic Boundaries
Never treat technical docs as flat text. Transpile multi-dialect sources into structured MDX and chunk along structural heading trees for precise LLM retrieval.
Slotted & Frozen Dataclass Domain Architecture
All domain models use slots=True and frozen=True (Rule 12):
AutodocParameter(slots=True, frozen=True)AutodocSignature(slots=True, frozen=True)LinkDiagnostic(slots=True, frozen=True)LinkValidationReport(slots=True, frozen=True)DocChunk(slots=True, frozen=True)
The Visual Brief Pillar
When completing multi-package documentation compilation runs or MDX transpilation sessions, synthesize anchor graph coverage, broken cross-reference counts, and mock virtualization pass rates into a standalone interactive HTML visual brief written to %TEMP%\hf-doc-builder-<timestamp>.html. Render the AST anchor dependency graph as a Mermaid graph LR.
Mandatory Checkpoint Gates
Before publishing any compiled documentation or committing MDX transforms:
- Gate 1 (Anchor Integrity): Assert zero broken internal
[anchor](#heading)links in the compiled documentation output. - Gate 2 (Mock Virtualization): Assert all zero-dependency mock stubs pass without importing live packages during build.
- Gate 3 (Cross-Package Links): Assert all cross-package references resolve to existing anchors in the target package documentation.
Anti-Patterns
- Environment-Coupled Inspection — Requiring full CUDA / GPU machine learning environments to extract docstrings instead of utilizing PEP 302/451 meta-path mock virtualization.
- Unshielded Codeblock Link Crawling — Running regex link matchers over unparsed Markdown without stripping code fences, producing false-positive link errors on Python code syntax.
- Arbitrary Token Slicing — Chopping technical documentation into fixed 512-token chunks that split method signatures from parameter descriptions instead of bounding along heading trees.
- Orphan Page Accumulation — Publishing documentation pages that are omitted from
_toctree.ymlnavigation manifests, creating unindexed dark documentation. - Unbounded Relative Route Failure — Failing on extensionless links (
./quickstart) instead of attempting multi-extension resolution (.md,.mdx,/index.md).
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.