feat: improve documentation quality with real data

- Extract file-level docstrings from Python files (module-level string expressions) - Use __init__.py docstrings as module doc_summary - Use file docstrings as file purpose in layout tables (instead of 'Source file') - Populate module outbound_modules/inbound_modules from import edges (internal only) - Make filename sanitization consistent (sanitize_for_link matches sanitize_filename) - Clean up stale .md files from previous runs before generating - Fill ARCHITECTURE.md template with real layout, modules index, and critical points - Add file_docstring field to ParsedModule and file_purpose to FileDoc
2026-02-15 04:10:20 +03:00
parent 25fdf400fa
commit c095560e13
24 changed files with 936 additions and 518 deletions
--- a/test-project/docs/architecture/files/src__utils.py.md
+++ b/test-project/docs/architecture/files/src__utils.py.md
@@ -0,0 +1,194 @@
+# File: ./src/utils.py
+
+- **Module:** utils
+- **Defined symbols:** 4
+- **Imports:** 2
+
+<!-- MANUAL:BEGIN -->
+## File intent (manual)
+<FILL_MANUALLY>
+<!-- MANUAL:END -->
+
+---
+
+## Imports & file-level dependencies
+<!-- ARCHDOC:BEGIN section=file_imports -->
+> Generated. Do not edit inside this block.
+- json
+- os
+<!-- ARCHDOC:END section=file_imports -->
+
+---
+
+## Symbols index
+<!-- ARCHDOC:BEGIN section=symbols_index -->
+> Generated. Do not edit inside this block.
+- `load_config` (Function)
+- `save_config` (Function)
+- `get_file_size` (Function)
+- `format_bytes` (Function)
+<!-- ARCHDOC:END section=symbols_index -->
+
+---
+
+## Symbol details
+
+<!-- ARCHDOC:BEGIN symbol id=load_config --><a id="load_config"></a>
+
+### `load_config`
+- **Kind:** Function
+- **Signature:** `def load_config(config_path: str)`
+- **Docstring:** `Load configuration from a JSON file.`
+
+#### What it does
+<!-- ARCHDOC:BEGIN section=purpose -->
+extracted from AST
+<!-- ARCHDOC:END section=purpose -->
+
+#### Relations
+<!-- ARCHDOC:BEGIN section=relations -->
+**Outbound calls (best-effort):**
+
+**Inbound (used by) (best-effort):**
+<!-- ARCHDOC:END section=relations -->
+
+#### Integrations (heuristic)
+<!-- ARCHDOC:BEGIN section=integrations -->
+- HTTP: no
+- DB: no
+- Queue/Tasks: no
+<!-- ARCHDOC:END section=integrations -->
+
+#### Risk / impact
+<!-- ARCHDOC:BEGIN section=impact -->
+- fan-in: 0
+- fan-out: 2
+- cycle participant: no
+- critical: no
+<!-- ARCHDOC:END section=impact -->
+
+<!-- MANUAL:BEGIN -->
+#### Manual notes
+<FILL_MANUALLY>
+<!-- MANUAL:END -->
+<!-- ARCHDOC:END symbol id=load_config -->
+
+<!-- ARCHDOC:BEGIN symbol id=save_config --><a id="save_config"></a>
+
+### `save_config`
+- **Kind:** Function
+- **Signature:** `def save_config(config: dict, config_path: str)`
+- **Docstring:** `Save configuration to a JSON file.`
+
+#### What it does
+<!-- ARCHDOC:BEGIN section=purpose -->
+extracted from AST
+<!-- ARCHDOC:END section=purpose -->
+
+#### Relations
+<!-- ARCHDOC:BEGIN section=relations -->
+**Outbound calls (best-effort):**
+
+**Inbound (used by) (best-effort):**
+<!-- ARCHDOC:END section=relations -->
+
+#### Integrations (heuristic)
+<!-- ARCHDOC:BEGIN section=integrations -->
+- HTTP: no
+- DB: no
+- Queue/Tasks: no
+<!-- ARCHDOC:END section=integrations -->
+
+#### Risk / impact
+<!-- ARCHDOC:BEGIN section=impact -->
+- fan-in: 0
+- fan-out: 2
+- cycle participant: no
+- critical: no
+<!-- ARCHDOC:END section=impact -->
+
+<!-- MANUAL:BEGIN -->
+#### Manual notes
+<FILL_MANUALLY>
+<!-- MANUAL:END -->
+<!-- ARCHDOC:END symbol id=save_config -->
+
+<!-- ARCHDOC:BEGIN symbol id=get_file_size --><a id="get_file_size"></a>
+
+### `get_file_size`
+- **Kind:** Function
+- **Signature:** `def get_file_size(filepath: str)`
+- **Docstring:** `Get the size of a file in bytes.`
+
+#### What it does
+<!-- ARCHDOC:BEGIN section=purpose -->
+extracted from AST
+<!-- ARCHDOC:END section=purpose -->
+
+#### Relations
+<!-- ARCHDOC:BEGIN section=relations -->
+**Outbound calls (best-effort):**
+
+**Inbound (used by) (best-effort):**
+<!-- ARCHDOC:END section=relations -->
+
+#### Integrations (heuristic)
+<!-- ARCHDOC:BEGIN section=integrations -->
+- HTTP: no
+- DB: no
+- Queue/Tasks: no
+<!-- ARCHDOC:END section=integrations -->
+
+#### Risk / impact
+<!-- ARCHDOC:BEGIN section=impact -->
+- fan-in: 0
+- fan-out: 1
+- cycle participant: no
+- critical: no
+<!-- ARCHDOC:END section=impact -->
+
+<!-- MANUAL:BEGIN -->
+#### Manual notes
+<FILL_MANUALLY>
+<!-- MANUAL:END -->
+<!-- ARCHDOC:END symbol id=get_file_size -->
+
+<!-- ARCHDOC:BEGIN symbol id=format_bytes --><a id="format_bytes"></a>
+
+### `format_bytes`
+- **Kind:** Function
+- **Signature:** `def format_bytes(size: int)`
+- **Docstring:** `Format bytes into a human-readable string.`
+
+#### What it does
+<!-- ARCHDOC:BEGIN section=purpose -->
+extracted from AST
+<!-- ARCHDOC:END section=purpose -->
+
+#### Relations
+<!-- ARCHDOC:BEGIN section=relations -->
+**Outbound calls (best-effort):**
+
+**Inbound (used by) (best-effort):**
+<!-- ARCHDOC:END section=relations -->
+
+#### Integrations (heuristic)
+<!-- ARCHDOC:BEGIN section=integrations -->
+- HTTP: no
+- DB: no
+- Queue/Tasks: no
+<!-- ARCHDOC:END section=integrations -->
+
+#### Risk / impact
+<!-- ARCHDOC:BEGIN section=impact -->
+- fan-in: 0
+- fan-out: 0
+- cycle participant: no
+- critical: no
+<!-- ARCHDOC:END section=impact -->
+
+<!-- MANUAL:BEGIN -->
+#### Manual notes
+<FILL_MANUALLY>
+<!-- MANUAL:END -->
+<!-- ARCHDOC:END symbol id=format_bytes -->