selfdoc 0.4.2__tar.gz → 0.4.3__tar.gz

selfdoc-0.4.3/.rlsbl/changes/.validated

@@ -0,0 +1 @@
+4d83ba7aaaeb1c46980dac638bc4a110c909781a

selfdoc-0.4.3/.rlsbl/changes/0.4.3.jsonl

@@ -0,0 +1,14 @@
+{"commits":["a3a79e095f830e86e3af6e0c91f332c2d0e3329b"],"user_facing":true,"description":"Directive catalog now includes descriptions, attribute specs, and usage examples for all core directives","type":"feature"}
+{"commits":["4824bea604f4201072dc404ee7f82b13a1ef1967"],"user_facing":true,"description":"Generated API and CLI reference pages now appear in organized sidebar groups","type":"feature"}
+{"commits":["7ef991c8f04d43572d00c26063511cafd5b26204"],"user_facing":false}
+{"commits":["4576e3a555693e2c8276917f5dbfc5dbb8038244"],"user_facing":false}
+{"commits":["43d35c2d58d0ae793d96b6e22907cff32678adfc"],"user_facing":false}
+{"commits":["dff95f7d6016c794066a4b6cf62547b156472fec"],"user_facing":false}
+{"commits":["cc28dff179806cb90cac6ec5893176175820e3ac"],"user_facing":false}
+{"commits":["8a52b31439bafe5e7fdce77785ae1a1ce8de6099"],"user_facing":false}
+{"commits":["28f4ee127fa09d1fc5b84ee03567043d23e24601"],"user_facing":false}
+{"commits":["f0e4cc383154cd05097c066f6eba2e606cd1518d"],"user_facing":false}
+{"commits":["20b46367718298885f83226e1ba37a0c10300979"],"user_facing":false}
+{"commits":["586d6738a1293ab5395c7027a2e32758c76a4f99"],"user_facing":false}
+{"commits":["6b02f79db1953a533dd37718abfd0afd86c85e47"],"user_facing":false}
+{"commits":["b3577a113db28097e22b375a4ff04238ae7d79df"],"user_facing":false}

selfdoc-0.4.3/.rlsbl/changes/0.4.3.md

@@ -0,0 +1,6 @@
+## 0.4.3
+
+### Features
+
+- Directive catalog now includes descriptions, attribute specs, and usage examples for all core directives
+- Generated API and CLI reference pages now appear in organized sidebar groups

selfdoc-0.4.3/.selfdoc/hashes/hashes.json

@@ -0,0 +1,138 @@
+{
+  "architecture.md": {
+    "content": "fc65c48b75f2d0f3f7aad3a402174473c1b64bec70db83bcd1b5b395b7be3629",
+    "description": "464747f099e75e988a325270cbdbb36c693ea208de0b2d943ff24b5f5252392c"
+  },
+  "cli-build.md": {
+    "content": "4f441939ec1d3d8343c42044480f4801e8e206e9f773412450b8856fe6ff7479",
+    "description": "11a0aaee6da7ee4c35003138aab30c0da61a8dd3bf5e044018aa70f6bfbf0ec1"
+  },
+  "cli-check.md": {
+    "content": "947cf39b048aaee0ac9690c1adc4ce51d9e97312e20c9ee555e68cc26924e823",
+    "description": "83e8642d203e66ffba0b975b220466ca1b8b7c46c931b3a8a1bdbd0a07b1d3a3"
+  },
+  "cli-deploy.md": {
+    "content": "c0767fe6deef9f08905033d612278aab70344a1ed2deaf95288b57fc0f08f361",
+    "description": "ad27bfa7ab8fc96330481bc3ed07ab64e31d6ec4ab467b224258c26b4a699ff7"
+  },
+  "cli-gen-data.md": {
+    "content": "3abfac56ea661721aa278eba03e4ce9951b30f1f92bc51112005a1f81b159637",
+    "description": "a68ffec614fa35a26edcfa34140521954e51c08774d98227ed53c394eafc7f55"
+  },
+  "cli-gen.md": {
+    "content": "293e1f4ed0cc55c0ea22a6e344794af46209ad96d20ec10fca0b2f9b11aad779",
+    "description": "f1d3d11f4f35831ff951eb13fbed3d4f20cdb7532b6313c1fa6261d3fcf792ef"
+  },
+  "cli-index.md": {
+    "content": "de219d0efb796b7b4f3ab24244cc41b4405ea19559c5f2d280636358e0e6be3e",
+    "description": "c6543973c3b8332ad546e3bdecc2541b5a88399c97d5216150b7f104dd055f2f"
+  },
+  "cli-init.md": {
+    "content": "5e8f0f46ebcf5e1e9651a81aa411a02184fe0b4b996fc07bcd537f4e66aff050",
+    "description": "6d1e068f0f9e76336b37a28f39ba59e7553d671158007299679ed23c4edd869b"
+  },
+  "cli-serve.md": {
+    "content": "ea2aadd9609b20c23f3382af79ee0b3e0c89542732939884ee446cf01ca25d69",
+    "description": "88323d7eb608336718f90d35a2f827a48b52aa27543aaa1dde3d2b130657d9de"
+  },
+  "configuration.md": {
+    "content": "4858f37dc862255798ce6f27a87e609e8cffa13a7a0dd605260eab9d5bc43f31",
+    "description": "d30e4e9e4c1b60a8bc5b61174320ec4ea58b7d7f378bd60584d9ec2d0299e0cd"
+  },
+  "deployment.md": {
+    "content": "496d3905a141686a3e00caa8b133f3e3340e46598789202590a35c81d1059427",
+    "description": "f9f30e6caa4ef2763b8df268eea782c65657392ebee25c2f806caaa8a1e9c269"
+  },
+  "directives.md": {
+    "content": "a4f4410da54796aa0054f1947929f55d7e42a4c73bb55053bda4d7ffcd7384eb",
+    "description": "85994821a561754f8f44d5f9726876a05998ae9ba9dff245d958f7fbbddd7dc2"
+  },
+  "gen-index.md": {
+    "content": "b9a34b4f67c1d3c80a949b39ec62bb6ffcc946f1b9c7efd1a3374b59518edd8e",
+    "description": "bc0df72d8e79b08f319aad256d06b946ee719ef2bfc5beab3544f708f1725922"
+  },
+  "getting-started.md": {
+    "content": "1a220d72194fde13e4adbcf07ac15affabf61b67b130c45d9538a96cec398127",
+    "description": "071f168a9369107d2eab946a88d6cee06f098c7fb97f1cdf7285356e961a2b75"
+  },
+  "index.md": {
+    "content": "0215ae1728fae958fced933434f5d4d782965d8c384b326e94b15ccdc9a3806f",
+    "description": "fc5340d9da34d6f4b4d6aab857b5e533907bd2222539b52cf388475ff11c81d1"
+  },
+  "selfdoc-__main__.md": {
+    "content": "19efba25c48ca26ab78e1964836c7506e02f2ac715c4228aa48974b6af98f5c2",
+    "description": "351bacca1ca67f29e4598fd2a9e25b176c7b7a441016ac56835b9d8ce99689e0"
+  },
+  "selfdoc-build.md": {
+    "content": "21a93bac9ec86685860f63d50cf78bc87951236530fdf0794709c4d52872352c",
+    "description": "be6f20e435f122041e45ac095b9e0baba6daaed128896562056712660094d0f5"
+  },
+  "selfdoc-check.md": {
+    "content": "cd63364de4f6e66b0900caba4367c78dbed9810c33582045433cf0bee71d3ab1",
+    "description": "a8203524aa4a4dd2203eed62ad2fa11c802265649e05559b4f06c2ade06cb530"
+  },
+  "selfdoc-cli.md": {
+    "content": "580f2ec3b7a0badb7e03a3a71a4699d43aa3ff8698f7408560f11ecc11d0f857",
+    "description": "1ed3e1bca9ce5f9dd1cda9b7438f1814723fdc809ba1e565199ef3e6ce34f847"
+  },
+  "selfdoc-config.md": {
+    "content": "9df82b5c322f48946bdac68f0bbfd2e8d8c4e2fe43112f31c7a1c871362ef7a7",
+    "description": "d3a27e63a4064e9ed04a28f998f1eec89b9af346f9bca09580175324f02afa9c"
+  },
+  "selfdoc-deploy.md": {
+    "content": "d753004c1be5186890f34d42342bd4d4d9a0d35d45dc48eb74bb9eadf1036fe3",
+    "description": "aeedfc3bd7ba0d35c5fe3a92ac01ac06b2384daac5d7d448f2bc35953437e8af"
+  },
+  "selfdoc-directives.md": {
+    "content": "284db842f12b44acc1a7e8b0d043571a0c587b59e474a13858291beb389484c3",
+    "description": "49d75691be8336bd4b491b6be99439cd0e19c8cbe0deb76146c5dd038d94149c"
+  },
+  "selfdoc-extractors-go.md": {
+    "content": "837dc9c718e1645f4a73f19e4c1d0d0a5c86f64ccd905a0263e7c0227300fdcd",
+    "description": "5165de519d0ec8ad6f401a64d0cc7b34fce376f6c40021f7a02215d87683d814"
+  },
+  "selfdoc-extractors-python.md": {
+    "content": "5036efd3be125c1b6ff24ee9d2872611dad0812c3daee6be7f96d82e90e75307",
+    "description": "59015b730d7770ead6707d7442e18a896ff8833268db7d8f2f4872d1614a2ac8"
+  },
+  "selfdoc-extractors-typescript.md": {
+    "content": "26e8c76b2bb4ab115b891eb6690012804c2d9cb41d29b4ced08cb55b66b214d5",
+    "description": "f452e7c33e92de442795ae1e50ead8d17c0be8541a63e1d78db54b002fb513e2"
+  },
+  "selfdoc-extractors.md": {
+    "content": "585b695cab232ab64f87ef0b28c8547612e34192dbca6079a0eed522871d8cd1",
+    "description": "f9fafcab95df9229d672f91ffe5d6ca766958dcfe3c1638302d824621f962ff2"
+  },
+  "selfdoc-gen.md": {
+    "content": "b21477fe438d6743531de0c2a74524eb0d9e28969a10d728ecb921244939e5cf",
+    "description": "03f8cccc2ca955e46a9a08bb9cb50e5f9ffaf3c46bf2c01d24106e1f8a9eb45f"
+  },
+  "selfdoc-gendata.md": {
+    "content": "54e9a0a6aee2b422ced3b860c872362c65d940dae28ba3d0b79c3117bc234b62",
+    "description": "516999e8f3c505e0f46146652e521a0667d6a4fcc3132afcc12ba273fc1cf111"
+  },
+  "selfdoc-html.md": {
+    "content": "b56b50df5396c1e8f2633ba3def2011e4b34500c712caca6dc5e4153df18a843",
+    "description": "7cabc6a2a59f70a50a02132568e6cfd45ca58aad267764fda8120add86f8de89"
+  },
+  "selfdoc-resolver.md": {
+    "content": "4158312182ee977769882e9a4552ac2613f31bfa0dadb71be8bed0848861063d",
+    "description": "458c35bc81993667cf6f82d148af5f2993c72a273191c014011eb5f47b1c77b6"
+  },
+  "selfdoc-strictcli_support.md": {
+    "content": "cd50a69cdc65b253ce6826b050114f65c6b62ecc8f6b09b07c4a5e212d1d1b74",
+    "description": "0c1d40804347c9e9783377363c6268adb29a83f82fb4a8cd07c362082b845837"
+  },
+  "selfdoc-tokenizer.md": {
+    "content": "c1ba210f48e96dd2747309a8de17f49a101fc15f87ced867dd423ebe29dc43d4",
+    "description": "d2a949819b783e024b634f56c0cd49533fcaa40a67dfb67c39b5b99314899029"
+  },
+  "selfdoc.md": {
+    "content": "740137aa79607266cf4710eda34a20f09e042eb59aa74d888e1ce1c21e49b8d4",
+    "description": "4b2eeed0350ea775619b4bdffaf63dbb7b4e1f7c618c81630cb1ea79a7e535b0"
+  },
+  "theming.md": {
+    "content": "bb327170ca977b166a27223ee5ab21c8049fafc85f34519aeef10d1aac7e1506",
+    "description": "47828070bf38ec6e6e1ec94a0bd10af2f813ffe77625fbe6a5cac232beae9d2e"
+  }
+}

{selfdoc-0.4.2 → selfdoc-0.4.3}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 # Changelog
 
+## 0.4.3
+
+### Features
+
+- Directive catalog now includes descriptions, attribute specs, and usage examples for all core directives
+- Generated API and CLI reference pages now appear in organized sidebar groups
+
 ## 0.4.2
 
 ### Features

{selfdoc-0.4.2 → selfdoc-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: selfdoc
-Version: 0.4.2
+Version: 0.4.3
 Summary: Code-aware static site generator with directive-based content extraction
 Project-URL: Repository, https://github.com/smm-h/selfdoc
 Author: smm-h

selfdoc-0.4.3/docs/architecture.md

@@ -0,0 +1,240 @@
+---
+title: Architecture
+description: "Internal architecture of selfdoc: the Markdown tokenizer, rendering pipeline, language extractors, directive resolver, and build system."
+order: 60
+---
+
+# Architecture
+
+This page documents the internal design of selfdoc for contributors and anyone interested in extending or debugging the system.
+
+## Overview
+
+The selfdoc build pipeline transforms Markdown templates containing directive markers into a fully-featured static HTML site through a sequence of well-separated stages. Each stage receives the output of the previous one and produces a deterministic result, making the overall system straightforward to test, debug, and extend:
+
+1. **Scan** -- walk `docs/` for `.md` files, parse frontmatter
+2. **Resolve directives** -- replace directive markers with generated Markdown content (from source code or content transforms)
+3. **Tokenize** -- split the resolved Markdown into typed block tokens
+4. **Render** -- dispatch each token to a block-level HTML renderer
+5. **Post-process** -- apply heuristic transforms (code tabs, step guides, API entries, definitions, LCP promotion)
+6. **Generate HTML** -- wrap rendered content in a full page shell with navigation, metadata, and styles
+7. **Auxiliary output** -- generate sitemap, Atom feed, search index, OG images, `llms.txt`, and compressed companions
+
+Each stage is a pure function of its input, making the system easy to test and reason about. There is no shared mutable state between stages.
+
+## Tokenizer
+
+**Module:** `selfdoc/tokenizer.py` -- the tokenizer is a standalone, zero-dependency module that splits Markdown source into a flat list of typed block tokens. It has no imports from selfdoc and is designed for reuse outside the project. The tokenizer guarantees that every source line belongs to exactly one token, with no gaps or overlaps between adjacent tokens.
+
+### Token types
+
+The tokenizer produces 11 token types, each represented as a `@dataclass` with `start` and `end` line numbers (1-based). These types cover the full range of Markdown block-level constructs that selfdoc supports, from headings and code blocks to tables, lists, and directives:
+
+| Token | Represents |
+|-------|-----------|
+| `Heading` | ATX heading (`#` through `######`) with level and text |
+| `CodeBlock` | Fenced code block with language, content lines, and annotations |
+| `Table` | Pipe-delimited table rows |
+| `UnorderedList` | Items starting with `-` or `*` |
+| `OrderedList` | Items starting with `1.`, `2.`, etc. |
+| `Blockquote` | `>` prefixed lines, with optional admonition type |
+| `DefinitionList` | Term/definition pairs (DL/DT/DD) |
+| `ThematicBreak` | `---`, `***`, or `___` |
+| `BlankLine` | Empty separator lines |
+| `Directive` | The legacy `:::name arg` / `:::` syntax (tokenizer-level) |
+| `Paragraph` | Everything else -- contiguous non-blank lines |
+
+All tokens are combined into a `Block` union type. The tokenizer guarantees full coverage: every source line belongs to exactly one token, with no gaps or overlaps.
+
+### Design rationale
+
+The tokenizer exists as a separate module rather than being embedded as inline parsing logic within the HTML renderer. This separation serves two important purposes and keeps the architecture clean by ensuring that parsing concerns are decoupled from rendering concerns:
+
+- **Dual consumers:** both the rendering pipeline and the lint system operate on tokens. The lint system needs line numbers for diagnostics, and the renderer needs structured data for dispatch.
+- **Testability:** tokenization can be tested in isolation without invoking HTML generation or directive resolution.
+
+## Rendering Pipeline
+
+**Module:** `selfdoc/html.py`, function `md_to_html` -- the rendering pipeline converts resolved Markdown to HTML through a three-phase process that cleanly separates tokenization, block-level rendering, and heuristic post-processing into distinct stages. Each phase has a single responsibility, which makes the pipeline easy to test and debug independently.
+
+### Phase 1: Tokenize and render blocks
+
+`md_to_html` calls the tokenizer, then iterates over the resulting tokens, dispatching each to `_render_block`. This function pattern-matches on token type and delegates to specialized renderers (`_render_heading`, `_render_code_block`, `_render_table`, `_render_definition_list`, etc.). The first H1 heading is consumed for use as the page title and not rendered inline.
+
+### Phase 2: Post-processors
+
+After block rendering produces a joined HTML string, a series of regex-based post-processors transform the output to detect cross-block patterns and apply semantic enhancements that cannot be determined from individual tokens alone:
+
+- **Code tabs** (`_group_code_tabs`): consecutive code blocks with different languages are wrapped in a tabbed interface
+- **Step guides** (`_apply_step_guides`): ordered lists following headings containing "step", "guide", or "tutorial" receive a `class="steps"` for special styling
+- **API entries** (`_wrap_api_entries`): sequences of h3/h4 + code block + description paragraph are wrapped in `<div class="api-entry">` cards
+- **Definitions** (`_apply_definitions`): definitional patterns after headings get `<dfn>` wrapping for semantic markup and glossary cross-linking
+- **LCP promotion**: the first image in the page is promoted from `loading="lazy"` to `fetchpriority="high" loading="eager"` for faster Largest Contentful Paint
+
+### Phase 3: Page assembly
+
+The `generate_html` function wraps the per-page HTML in a full document shell that includes sidebar navigation, breadcrumbs, canonical URLs, OpenGraph tags, structured data (JSON-LD), theme CSS, and JavaScript for interactive features like code tabs and full-text search.
+
+### Why post-processors operate on HTML strings
+
+Post-processors run after block rendering rather than on tokens because they detect cross-block patterns (e.g., "three consecutive code blocks" or "a heading followed by an ordered list"). The token stream is flat, making it natural to detect these patterns with regex on the rendered output. This keeps the renderer simple (one token in, one HTML fragment out) and moves heuristic logic to an explicit post-processing phase.
+
+## Directive System
+
+**Modules:** `selfdoc/directives.py` (parser), `selfdoc/resolver.py` (dispatch), `selfdoc/content.py` (content directives) -- directives are the core mechanism for pulling live information from source code into documentation. They bridge the gap between your codebase and your Markdown templates, ensuring that documentation content always reflects the current state of the implementation.
+
+### Syntax
+
+The directive parser recognizes a structured marker syntax that supports both self-closing one-liner directives and multi-line block directives with attributes and body content. Directives inside fenced code blocks are automatically ignored, and unclosed block directives at end-of-file produce a clear error:
+
+| Marker | Purpose |
+|--------|---------|
+| `:-: name key="value"` | One-liner directive |
+| `:<: name [attrs]` | Block open |
+| `:@: key="value"` | Additional attribute line |
+| `:=:` | Body separator |
+| `::: content` | Body line |
+| `:>:` | Block close |
+
+Directives inside fenced code blocks are ignored. Unclosed block directives at EOF produce a `DirectiveError`.
+
+### Resolver dispatch chain
+
+When a directive is encountered during the build, the resolver created by `make_resolver` processes it through a three-level dispatch chain that tries each handler in order and stops at the first match:
+
+1. **Content directives** -- `resolve_content` handles callouts (`callout-note`, `callout-warning`, etc.) and `list-glossary`. These transform body content into styled HTML without needing source code access. If the directive matches a content type, resolution stops here.
+
+2. **Custom directives** -- if the project's `selfdoc.json` declares a `"directives"` map, the resolver loads the referenced Python script and calls its `resolve(attrs, config, body)` function. This allows project-specific extraction logic.
+
+3. **Language extractor** -- the built-in extractor for the project's configured language handles the directive. This is the most common path for code-aware directives (`ref`, `table-schema`, `code-test`, `code-help`, `table-config`).
+
+If none of these can handle the directive, the resolver emits an inline error marker (`> *[selfdoc: ...]*`) that is visible in the rendered output.
+
+### Built-in directives
+
+The directive catalog in `selfdoc/catalog.py` defines two categories of directives, cleanly separating what is currently functional and shipped from what is declared as a valid name but planned for future implementation. This approach allows documentation authors to reference future directives without triggering parse errors:
+
+- **Core directives** (shipped and functional): `ref`, `table-schema`, `code-test`, `code-help`, `table-config`, callouts, and `list-glossary`
+- **Future directives** (declared, parse-valid, not yet implemented): a large set organized by prefix -- `table-*`, `code-*`, `list-*`, `callout-*`, `prose-*`
+
+Declaring future directives means the parser accepts them without error, allowing documentation authors to mark intent before extraction logic exists.
+
+## Language Extractors
+
+**Module:** `selfdoc/extractors/` -- each supported language has a dedicated extractor module that implements the `LanguageExtractor` protocol, providing language-specific logic for resolving directives, detecting source files, and enumerating public symbols for coverage analysis.
+
+### The protocol
+
+```python
+class LanguageExtractor(Protocol):
+    @property
+    def name(self) -> str: ...
+    def detect(self, dir_path: str) -> bool: ...
+    def resolve_path(self, path_arg, source_paths, base_dir) -> str | None: ...
+    def extract(self, directive_name, attrs, body, source_paths, base_dir) -> str: ...
+    def file_extensions(self) -> list[str]: ...
+    def public_symbols(self, file_path: str) -> list[str]: ...
+```
+
+The protocol is `runtime_checkable`, allowing the registry to validate extractors at import time.
+
+### Implementations
+
+| Extractor | Language | Parsing strategy |
+|-----------|----------|-----------------|
+| `PythonExtractor` | Python | `ast` module -- full AST parsing for accurate symbol extraction |
+| `GoExtractor` | Go | Regex-based -- matches exported identifiers, struct fields, function signatures |
+| `TypeScriptExtractor` | TypeScript, JavaScript | Regex-based -- matches exports, interfaces, type aliases |
+
+The Python extractor uses the `ast` module because Python's grammar makes regex-based extraction unreliable (decorators, multiline signatures, nested classes). Go and TypeScript have simpler export conventions (capitalized names in Go, explicit `export` keywords in TypeScript) that regex handles reliably.
+
+### What each directive extracts
+
+| Directive | Extraction target |
+|-----------|------------------|
+| `ref` | Module docstring, exported functions, classes with their signatures and docs |
+| `table-schema` | Dataclass/struct/interface fields rendered as a Markdown table |
+| `code-test` | Test function source code (whole file or specific function) |
+| `code-help` | CLI argument parser definitions and help text |
+| `table-config` | Configuration keys with types and descriptions |
+
+### Language detection
+
+The extractor registry also provides auto-detection through the `detect_language` function, which probes for marker files (`pyproject.toml` for Python, `go.mod` for Go, `package.json` or `tsconfig.json` for TypeScript) in a fixed priority order. This powers the `selfdoc init` command, allowing it to automatically configure the correct language without user input.
+
+## Build Pipeline
+
+**Module:** `selfdoc/build.py`, function `build` -- the build function orchestrates the full site generation from Markdown templates to a deployable static site, coordinating directive resolution, HTML rendering, auxiliary file generation, and asset copying.
+
+### Main pipeline
+
+1. Load config from `selfdoc.json`
+2. Walk `docs/` for `.md` templates (skipping the output directory)
+3. Parse frontmatter from each file (YAML between `---` fences)
+4. Resolve directives using the project's configured language extractor
+5. Pass resolved Markdown through `generate_html` (which tokenizes, renders, and post-processes)
+6. Copy non-Markdown assets (images, CSS, scripts) to the output directory
+
+### Auxiliary file generation
+
+After the main HTML pipeline completes, the build generates several companion files that enhance discoverability, accessibility, and performance of the published site. These auxiliary outputs are all derived from the same page metadata and content used by the HTML renderer, ensuring consistency across formats:
+
+- **Sitemap** (`sitemap.xml`): standard sitemap with page URLs and last-modified dates
+- **Atom feed** (`feed.xml`): full Atom feed for RSS readers, respecting per-page `feed: false` frontmatter
+- **Search index** (`search-index.json`): JSON index built from headings and content for client-side search
+- **OG images**: OpenGraph card PNGs for social sharing (uses predraw if available, falls back to pure-Python PNG generation)
+- **`llms.txt`**: a structured plain-text index of the site for LLM consumption, plus an `llms-full.txt` with all content
+- **Compressed companions**: gzip (and brotli if available) pre-compressed versions of text-based output files for efficient serving
+
+### Staleness tracking
+
+The build computes content hashes for each page and persists them. The check command later uses these hashes to detect when page content has changed but its description has not been updated -- a common source of stale SEO metadata.
+
+### Atomic writes and concurrency
+
+File writes to shared state use atomic write patterns (write to a temporary file, then `os.replace`). This prevents partial reads if another process accesses the output directory during a build.
+
+## Lint System
+
+**Module:** `selfdoc/check.py` -- the `check` command validates documentation quality across three dimensions: directive correctness, documentation coverage, and SEO best practices. It operates on the tokenized representation of each page, giving it access to structured information without needing to re-parse raw Markdown.
+
+### Directive validation
+
+For every directive in every documentation template file, the checker performs a full resolution attempt using the project's configured language extractor to verify that the directive would succeed at build time. This catches broken module paths, missing symbols, and malformed attributes before they reach production:
+
+1. Parses the directive (validating syntax and name against the catalog)
+2. Attempts full resolution using the project's extractor
+3. Reports OK or FAILED with the specific error
+
+This catches broken paths, missing symbols, and malformed attributes before they reach production.
+
+### Coverage analysis
+
+Coverage measures how many public symbols in the source code are referenced by at least one directive. The analysis uses each extractor's `public_symbols` method to enumerate exported symbols, then cross-references against successfully resolved directives.
+
+### SEO lint checks
+
+The lint system operates on tokens rather than raw Markdown, which gives it access to structured information like heading levels, image alt text, and link targets without re-parsing. There are currently 14 checks covering metadata, content structure, and accessibility:
+
+| Code | Check |
+|------|-------|
+| SEO001 | Multiple H1 headings |
+| SEO002 | Heading level gaps (e.g., H2 followed by H4) |
+| SEO003 | Empty image alt text |
+| SEO004 | Title too long for search results |
+| SEO006 | Missing meta description |
+| SEO007-008 | Link and structural diagnostics |
+| SEO009 | Description too short |
+| SEO010 | Description too long |
+| SEO011-012 | Content quality signals |
+| SEO013 | No title source (no frontmatter title and no H1) |
+| SEO014 | Meaningless alt text (e.g., "image", "screenshot") |
+| SEO015 | Generic anchor text (e.g., "click here", "link") |
+
+### Staleness detection
+
+When a page's content hash differs from the last build but its description hash is unchanged, the checker flags it as potentially stale. This catches the common case where documentation content is updated but the frontmatter description (used in search results and social cards) still describes the old content.
+
+### Why tokens, not raw Markdown
+
+Operating on tokens rather than raw text means the lint system gets pre-parsed structure for free. It does not need to re-implement heading detection, code block boundaries, or list parsing. It can reliably distinguish "an image inside a code block" (should not trigger SEO003) from "an image in body text" (should trigger it).

selfdoc-0.4.3/docs/cli-build.md

@@ -0,0 +1,19 @@
+---
+title: selfdoc build
+description: "Reference for the selfdoc build command — usage, flags, arguments, and examples for the build subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 1
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc build
+
+Build the documentation site
+
+## Flags
+
+| Name | Short | Type | Default | Env | Description |
+|------|-------|------|---------|-----|-------------|
+| `--warn-only` |  | bool |  |  | (deprecated, no-op) Warnings are now non-fatal by default |
+| `--no-commit` |  | bool |  |  | Skip auto-committing changed files |

selfdoc-0.4.3/docs/cli-check.md

@@ -0,0 +1,21 @@
+---
+title: selfdoc check
+description: "Reference for the selfdoc check command — usage, flags, arguments, and examples for the check subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 2
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc check
+
+Check documentation coverage and consistency
+
+## Flags
+
+| Name | Short | Type | Default | Env | Description |
+|------|-------|------|---------|-----|-------------|
+| `--ignore` |  | str |  |  | Comma-separated SEO codes to suppress (e.g., SEO007,SEO008) |
+| `--format` |  | str | text |  | Output format (default: text) |
+| `--warn-only` |  | bool |  |  | (deprecated, no-op) Warnings are now non-fatal by default |
+| `--no-commit` |  | bool |  |  | Skip auto-committing changed files |

selfdoc-0.4.3/docs/cli-deploy.md

@@ -0,0 +1,12 @@
+---
+title: selfdoc deploy
+description: "Reference for the selfdoc deploy command — usage, flags, arguments, and examples for the deploy subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 3
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc deploy
+
+Deploy the documentation site

selfdoc-0.4.3/docs/cli-gen-data.md

@@ -0,0 +1,18 @@
+---
+title: selfdoc gen-data
+description: "Reference for the selfdoc gen-data command — usage, flags, arguments, and examples for the gen-data subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 5
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc gen-data
+
+Generate data files by running sandboxed scripts
+
+## Flags
+
+| Name | Short | Type | Default | Env | Description |
+|------|-------|------|---------|-----|-------------|
+| `--no-commit` |  | bool |  |  | Skip auto-committing changed files |

selfdoc-0.4.3/docs/cli-gen.md

@@ -0,0 +1,18 @@
+---
+title: selfdoc gen
+description: "Reference for the selfdoc gen command — usage, flags, arguments, and examples for the gen subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 4
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc gen
+
+Auto-generate documentation pages from project structure
+
+## Flags
+
+| Name | Short | Type | Default | Env | Description |
+|------|-------|------|---------|-----|-------------|
+| `--no-commit` |  | bool |  |  | Skip auto-committing changed files |

selfdoc-0.4.3/docs/cli-index.md

@@ -0,0 +1,25 @@
+---
+title: selfdoc CLI Reference
+description: "Complete CLI reference for selfdoc — all available commands, subcommands, flags, arguments, and usage examples with detailed descriptions."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 0
+order: 91
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc CLI Reference
+
+Code-aware static site generator with directive-based content extraction
+
+Version: __version__
+
+## Commands
+
+- [init](cli-init.html) -- Initialize selfdoc in the current project
+- [build](cli-build.html) -- Build the documentation site
+- [serve](cli-serve.html) -- Serve the documentation site locally
+- [deploy](cli-deploy.html) -- Deploy the documentation site
+- [check](cli-check.html) -- Check documentation coverage and consistency
+- [gen](cli-gen.html) -- Auto-generate documentation pages from project structure
+- [gen-data](cli-gen-data.html) -- Generate data files by running sandboxed scripts

selfdoc-0.4.3/docs/cli-init.md

@@ -0,0 +1,18 @@
+---
+title: selfdoc init
+description: "Reference for the selfdoc init command — usage, flags, arguments, and examples for the init subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 6
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc init
+
+Initialize selfdoc in the current project
+
+## Flags
+
+| Name | Short | Type | Default | Env | Description |
+|------|-------|------|---------|-----|-------------|
+| `--no-commit` |  | bool |  |  | Skip auto-committing changed files |

selfdoc-0.4.3/docs/cli-serve.md

@@ -0,0 +1,18 @@
+---
+title: selfdoc serve
+description: "Reference for the selfdoc serve command — usage, flags, arguments, and examples for the serve subcommand of the selfdoc CLI."
+generated: true
+nav_group: "CLI Reference"
+nav_order: 7
+---
+<!-- generated by selfdoc gen (strictcli), do not edit -->
+
+# selfdoc serve
+
+Serve the documentation site locally
+
+## Flags
+
+| Name | Short | Type | Default | Env | Description |
+|------|-------|------|---------|-----|-------------|
+| `--port` | `-p` | int | 8000 |  | Port to serve on (default: 8000) |