pystdoc 0.3.0__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {pystdoc-0.3.0/src/pystdoc.egg-info → pystdoc-0.5.0}/PKG-INFO +1 -1
- {pystdoc-0.3.0 → pystdoc-0.5.0}/pyproject.toml +1 -1
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/__init__.py +1 -1
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/design_engine.py +20 -10
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/doc_writer.py +47 -23
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/llm_client.py +85 -23
- {pystdoc-0.3.0 → pystdoc-0.5.0/src/pystdoc.egg-info}/PKG-INFO +1 -1
- {pystdoc-0.3.0 → pystdoc-0.5.0}/tests/test_docgen.py +2 -2
- {pystdoc-0.3.0 → pystdoc-0.5.0}/LICENSE +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/README.md +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/setup.cfg +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/cache.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/call_graph.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/cli.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/compilation_db.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/db.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/engine.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/hasher.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/parser_clang.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/parser_generic.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/parser_python.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/report_engine.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/scanner.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc/symbols.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc.egg-info/SOURCES.txt +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc.egg-info/dependency_links.txt +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc.egg-info/entry_points.txt +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc.egg-info/requires.txt +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/src/pystdoc.egg-info/top_level.txt +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/tests/test_designgen.py +0 -0
- {pystdoc-0.3.0 → pystdoc-0.5.0}/tests/test_reportgen.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pystdoc
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator.
|
|
5
5
|
Author: tab4moji
|
|
6
6
|
License: MIT
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "pystdoc"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.5.0"
|
|
8
8
|
description = "Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
authors = [
|
|
@@ -35,10 +35,23 @@ def parse_symbol_doc(md_path: Path) -> Dict[str, Any]:
|
|
|
35
35
|
if m_title:
|
|
36
36
|
data["title"] = m_title.group(1).strip()
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
38
|
+
# 1. Extract Top-Down Context if present
|
|
39
|
+
m_top_down = re.search(r"## 1\..*Top-Down.*\n([\s\S]*?)(?=\n## 2\.|\Z)", text, re.IGNORECASE)
|
|
40
|
+
if m_top_down:
|
|
41
|
+
data["context"] = m_top_down.group(1).strip()
|
|
42
|
+
|
|
43
|
+
# 2. Extract Bottom-Up Purpose (from new layout or legacy layout)
|
|
44
|
+
m_purpose_new = re.search(r"- \*\*Core Purpose\*\*:\s*([^\n]+)", text)
|
|
45
|
+
if m_purpose_new:
|
|
46
|
+
data["purpose"] = m_purpose_new.group(1).strip()
|
|
47
|
+
else:
|
|
48
|
+
m_purpose_legacy = re.search(r"## 1\..*(?:Design Intent|Purpose).*\n([\s\S]*?)(?=\n## 2\.|\Z)", text)
|
|
49
|
+
if m_purpose_legacy and not m_top_down:
|
|
50
|
+
data["purpose"] = m_purpose_legacy.group(1).strip()
|
|
51
|
+
elif m_top_down:
|
|
52
|
+
data["purpose"] = data["context"]
|
|
53
|
+
|
|
54
|
+
# 3. Extract Kind & Signature
|
|
42
55
|
m_kind = re.search(r"- \*\*(?:Symbol Kind|Kind)[^*]*\*\*:\s*`?([^`\n]+)`?", text, re.IGNORECASE)
|
|
43
56
|
if m_kind:
|
|
44
57
|
data["kind"] = m_kind.group(1).strip().split()[0]
|
|
@@ -46,20 +59,17 @@ def parse_symbol_doc(md_path: Path) -> Dict[str, Any]:
|
|
|
46
59
|
if m_sig:
|
|
47
60
|
data["signature"] = m_sig.group(1).strip()
|
|
48
61
|
|
|
49
|
-
|
|
62
|
+
# 4. Extract Callees & References (section 5 or 6)
|
|
63
|
+
m_callees = re.search(r"## [56]\..*(?:Called Functions|Callees).*\n([\s\S]*?)(?=\n## |\Z)", text, re.IGNORECASE)
|
|
50
64
|
if m_callees:
|
|
51
65
|
callee_lines = re.findall(r"- `([^`]+)`", m_callees.group(1))
|
|
52
66
|
data["callees"] = [c for c in callee_lines if c not in ("None", "none")]
|
|
53
67
|
|
|
54
|
-
m_refs = re.search(r"##
|
|
68
|
+
m_refs = re.search(r"## [56]\..*(?:Referencing Functions|References).*\n([\s\S]*?)(?=\n## |\Z)", text, re.IGNORECASE)
|
|
55
69
|
if m_refs:
|
|
56
70
|
ref_lines = re.findall(r"- `([^`]+)`", m_refs.group(1))
|
|
57
71
|
data["referencing_funcs"] = [r for r in ref_lines if r not in ("None", "none")]
|
|
58
72
|
|
|
59
|
-
m_context = re.search(r"## 6\..*\n([\s\S]*?)(?=\n## |\Z)", text)
|
|
60
|
-
if m_context:
|
|
61
|
-
data["context"] = m_context.group(1).strip()
|
|
62
|
-
|
|
63
73
|
return data
|
|
64
74
|
|
|
65
75
|
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""Markdown documentation generator for individual symbols and files with multi-language support."""
|
|
1
|
+
"""Markdown documentation generator for individual symbols and files with top-down/bottom-up layout and multi-language support."""
|
|
2
2
|
|
|
3
3
|
import os
|
|
4
4
|
import re
|
|
@@ -14,11 +14,11 @@ from pystdoc.symbols import Symbol, get_kind_prefix
|
|
|
14
14
|
|
|
15
15
|
|
|
16
16
|
def normalize_language(lang: Optional[str]) -> str:
|
|
17
|
-
"""Normalize language string into
|
|
17
|
+
"""Normalize language string into standard representation (e.g. 'Japanese', 'English')."""
|
|
18
18
|
if not lang:
|
|
19
19
|
return "English"
|
|
20
20
|
l_lower = lang.strip().lower()
|
|
21
|
-
if l_lower in ("japanese", "ja", "jp"):
|
|
21
|
+
if l_lower in ("japanese", "ja", "jp", "日本語"):
|
|
22
22
|
return "Japanese"
|
|
23
23
|
elif l_lower in ("english", "en"):
|
|
24
24
|
return "English"
|
|
@@ -77,7 +77,10 @@ def format_symbol_section(
|
|
|
77
77
|
level: int = 2,
|
|
78
78
|
language: str = "English",
|
|
79
79
|
) -> str:
|
|
80
|
-
"""Format a symbol's documentation
|
|
80
|
+
"""Format a symbol's documentation with Top-Down explanation first, followed by Bottom-Up specifications."""
|
|
81
|
+
norm_lang = normalize_language(language)
|
|
82
|
+
is_ja = norm_lang == "Japanese"
|
|
83
|
+
|
|
81
84
|
h_prefix = "#" * level
|
|
82
85
|
kind_display = sym.kind
|
|
83
86
|
if sym.fqdn:
|
|
@@ -86,53 +89,71 @@ def format_symbol_section(
|
|
|
86
89
|
snippet = get_code_snippet(file_path, sym.line_start, sym.line_end)
|
|
87
90
|
lang_id = get_code_language(file_path.suffix)
|
|
88
91
|
|
|
92
|
+
default_purpose = f"`{sym.name}` の処理を実行する。" if is_ja else f"Executes `{sym.name}` operations."
|
|
93
|
+
default_top_down = (
|
|
94
|
+
f"- **役割**: 上位モジュールおよび呼び出し元から利用される `{sym.name}` の設計要素。\n- **データフロー**: 入力データを受け取り、要求された演算または状態遷移を実行する。"
|
|
95
|
+
if is_ja
|
|
96
|
+
else f"- **Role**: Architectural element of `{sym.name}` utilized by callers and parent components.\n- **Data Flow**: Accepts contextual inputs and performs state mutation or computation."
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
top_down_text = sym.top_down_context or default_top_down
|
|
100
|
+
bottom_up_purpose = sym.purpose or default_purpose
|
|
101
|
+
|
|
89
102
|
lines = [
|
|
90
103
|
f"{h_prefix} {sym.kind.capitalize()} Documentation: `{sym.name}`",
|
|
91
104
|
"",
|
|
92
|
-
"## 1.
|
|
93
|
-
|
|
105
|
+
"## 1. Top-Down Architectural Context & Role",
|
|
106
|
+
top_down_text,
|
|
107
|
+
"",
|
|
108
|
+
"## 2. Bottom-Up Implementation Specifications",
|
|
109
|
+
f"- **Core Purpose**: {bottom_up_purpose}",
|
|
110
|
+
]
|
|
111
|
+
if sym.overview:
|
|
112
|
+
lines.append(f"- **Implementation Overview**: {sym.overview}")
|
|
113
|
+
|
|
114
|
+
lines.extend([
|
|
94
115
|
"",
|
|
95
|
-
"##
|
|
116
|
+
"## 3. Basic Information",
|
|
96
117
|
f"- **Name**: `{sym.name}`",
|
|
97
118
|
f"- **FQDN**: `{sym.fqdn or sym.name}`",
|
|
98
119
|
f"- **Symbol Kind**: `{kind_display}`",
|
|
99
120
|
f"- **Location**: Line {sym.line_start} to Line {sym.line_end}",
|
|
100
|
-
]
|
|
121
|
+
])
|
|
101
122
|
if sym.signature:
|
|
102
123
|
lines.append(f"- **Signature / Type**: `{sym.signature}`")
|
|
103
124
|
|
|
104
125
|
if sym.parameters:
|
|
105
|
-
lines.extend(["", "##
|
|
126
|
+
lines.extend(["", "## 4. Parameters"])
|
|
106
127
|
for p in sym.parameters:
|
|
107
128
|
p_type = f": `{p.type_hint}`" if p.type_hint else ""
|
|
108
129
|
lines.append(f"- `{p.name}`{p_type}")
|
|
109
130
|
else:
|
|
110
|
-
lines.extend(["", "##
|
|
131
|
+
lines.extend(["", "## 4. Parameters", "- None"])
|
|
111
132
|
|
|
112
|
-
if sym.return_type or sym.outputs_note:
|
|
113
|
-
lines.extend(["", "##
|
|
133
|
+
if sym.return_type or sym.outputs_note or sym.inputs_note:
|
|
134
|
+
lines.extend(["", "## 5. Input / Return Specifications"])
|
|
135
|
+
if sym.inputs_note:
|
|
136
|
+
lines.append(f"- Input Constraints: {sym.inputs_note}")
|
|
137
|
+
lines.append(f"- Return Type: `{sym.return_type or 'void / None'}`")
|
|
114
138
|
if sym.outputs_note:
|
|
115
|
-
lines.append(f"-
|
|
139
|
+
lines.append(f"- Return Value & Side Effects: {sym.outputs_note}")
|
|
116
140
|
|
|
117
141
|
if sym.callees:
|
|
118
|
-
lines.extend(["", "##
|
|
142
|
+
lines.extend(["", "## 6. Called Functions"])
|
|
119
143
|
for c in sym.callees:
|
|
120
144
|
lines.append(f"- `{c}`")
|
|
121
145
|
elif sym.referencing_functions:
|
|
122
|
-
lines.extend(["", "##
|
|
146
|
+
lines.extend(["", "## 6. Referencing Functions"])
|
|
123
147
|
for r in sym.referencing_functions:
|
|
124
148
|
lines.append(f"- {r}")
|
|
125
149
|
|
|
126
|
-
if sym.top_down_context:
|
|
127
|
-
lines.extend(["", "## 6. Usage Context & Purpose", sym.top_down_context])
|
|
128
|
-
|
|
129
150
|
if snippet:
|
|
130
151
|
lines.extend(["", "## Source Code Snippet", f"```{lang_id}", snippet, "```"])
|
|
131
152
|
|
|
132
153
|
if sym.children:
|
|
133
154
|
lines.append("")
|
|
134
155
|
for child in sym.children:
|
|
135
|
-
lines.append(format_symbol_section(child, file_path, level=level + 1, language=
|
|
156
|
+
lines.append(format_symbol_section(child, file_path, level=level + 1, language=norm_lang))
|
|
136
157
|
|
|
137
158
|
return "\n".join(lines)
|
|
138
159
|
|
|
@@ -145,6 +166,7 @@ def write_single_symbol_doc(
|
|
|
145
166
|
language: str = "English",
|
|
146
167
|
) -> Path:
|
|
147
168
|
"""Write an individual symbol document with immediate flush."""
|
|
169
|
+
norm_lang = normalize_language(language)
|
|
148
170
|
docgen_dir = target_dir / ".docgen" / "documents"
|
|
149
171
|
docgen_dir.mkdir(parents=True, exist_ok=True)
|
|
150
172
|
|
|
@@ -153,7 +175,7 @@ def write_single_symbol_doc(
|
|
|
153
175
|
out_file = docgen_dir / f"{rel_path.as_posix()}.{k_prefix}.{sym_id}.md"
|
|
154
176
|
|
|
155
177
|
full_path = target_dir / rel_path
|
|
156
|
-
content = format_symbol_section(symbol, full_path, level=1, language=
|
|
178
|
+
content = format_symbol_section(symbol, full_path, level=1, language=norm_lang)
|
|
157
179
|
|
|
158
180
|
write_flushed_text(out_file, content + "\n")
|
|
159
181
|
return out_file
|
|
@@ -167,10 +189,11 @@ def write_individual_symbol_docs(
|
|
|
167
189
|
language: str = "English",
|
|
168
190
|
) -> List[Path]:
|
|
169
191
|
"""Recursively write documentation files for each individual symbol with immediate flush."""
|
|
192
|
+
norm_lang = normalize_language(language)
|
|
170
193
|
created_files: List[Path] = []
|
|
171
194
|
|
|
172
195
|
for sym in symbols:
|
|
173
|
-
out_file = write_single_symbol_doc(target_dir, rel_path, sym, prefix_name=prefix_name, language=
|
|
196
|
+
out_file = write_single_symbol_doc(target_dir, rel_path, sym, prefix_name=prefix_name, language=norm_lang)
|
|
174
197
|
created_files.append(out_file)
|
|
175
198
|
|
|
176
199
|
if sym.children:
|
|
@@ -180,7 +203,7 @@ def write_individual_symbol_docs(
|
|
|
180
203
|
rel_path,
|
|
181
204
|
sym.children,
|
|
182
205
|
prefix_name=child_prefix,
|
|
183
|
-
language=
|
|
206
|
+
language=norm_lang,
|
|
184
207
|
)
|
|
185
208
|
created_files.extend(child_files)
|
|
186
209
|
|
|
@@ -195,6 +218,7 @@ def write_symbol_doc(
|
|
|
195
218
|
language: str = "English",
|
|
196
219
|
) -> Path:
|
|
197
220
|
"""Write comprehensive file documentation with immediate flush."""
|
|
221
|
+
norm_lang = normalize_language(language)
|
|
198
222
|
docgen_dir = target_dir / ".docgen" / "documents"
|
|
199
223
|
docgen_dir.mkdir(parents=True, exist_ok=True)
|
|
200
224
|
|
|
@@ -215,7 +239,7 @@ def write_symbol_doc(
|
|
|
215
239
|
|
|
216
240
|
lines.append("")
|
|
217
241
|
for sym in symbols:
|
|
218
|
-
lines.append(format_symbol_section(sym, full_path, level=2, language=
|
|
242
|
+
lines.append(format_symbol_section(sym, full_path, level=2, language=norm_lang))
|
|
219
243
|
lines.append("")
|
|
220
244
|
|
|
221
245
|
write_flushed_text(out_file, "\n".join(lines).strip() + "\n")
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
"""LLM Client for LiteRT-LM, Ollama, and OpenAI-compatible endpoints with
|
|
1
|
+
"""LLM Client for LiteRT-LM, Ollama, and OpenAI-compatible endpoints with multi-language JSON normalization and retry resilience."""
|
|
2
2
|
|
|
3
3
|
import json
|
|
4
4
|
import os
|
|
@@ -31,6 +31,71 @@ def normalize_host_url(host: Optional[str]) -> str:
|
|
|
31
31
|
return h
|
|
32
32
|
|
|
33
33
|
|
|
34
|
+
def normalize_llm_json_dict(data: Dict[str, Any]) -> Dict[str, str]:
|
|
35
|
+
"""Normalize JSON dictionary keys from any language (English, Japanese, etc.) into standardized keys."""
|
|
36
|
+
normalized: Dict[str, str] = {}
|
|
37
|
+
|
|
38
|
+
for k in ("purpose", "目的", "設計意図", "意図", "description", "target", "role", "機能"):
|
|
39
|
+
if k in data and data[k]:
|
|
40
|
+
normalized["purpose"] = str(data[k]).strip()
|
|
41
|
+
break
|
|
42
|
+
|
|
43
|
+
for k in ("inputs", "入力", "引数", "パラメータ", "input", "arguments", "parameters"):
|
|
44
|
+
if k in data and data[k]:
|
|
45
|
+
normalized["inputs"] = str(data[k]).strip()
|
|
46
|
+
break
|
|
47
|
+
|
|
48
|
+
for k in ("outputs", "出力", "戻り値", "返り値", "output", "returns", "result"):
|
|
49
|
+
if k in data and data[k]:
|
|
50
|
+
normalized["outputs"] = str(data[k]).strip()
|
|
51
|
+
break
|
|
52
|
+
|
|
53
|
+
for k in ("overview", "概要", "要約", "説明", "summary", "details"):
|
|
54
|
+
if k in data and data[k]:
|
|
55
|
+
normalized["overview"] = str(data[k]).strip()
|
|
56
|
+
break
|
|
57
|
+
|
|
58
|
+
for k in ("significance", "重要性", "役割", "意義", "role"):
|
|
59
|
+
if k in data and data[k]:
|
|
60
|
+
normalized["significance"] = str(data[k]).strip()
|
|
61
|
+
break
|
|
62
|
+
|
|
63
|
+
for k in ("usage_scenario", "利用シナリオ", "使用シナリオ", "データフロー", "データ受け渡し", "scenario"):
|
|
64
|
+
if k in data and data[k]:
|
|
65
|
+
normalized["usage_scenario"] = str(data[k]).strip()
|
|
66
|
+
break
|
|
67
|
+
|
|
68
|
+
for k in ("top_down_summary", "要約", "概要", "全体設計要約", "summary"):
|
|
69
|
+
if k in data and data[k]:
|
|
70
|
+
normalized["top_down_summary"] = str(data[k]).strip()
|
|
71
|
+
break
|
|
72
|
+
|
|
73
|
+
return normalized
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def extract_json_from_text(raw_text: str) -> Dict[str, Any]:
|
|
77
|
+
"""Robustly extract and parse JSON object from LLM response text."""
|
|
78
|
+
clean = raw_text.strip()
|
|
79
|
+
# 1. Try markdown code block extraction
|
|
80
|
+
m_code = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", clean, re.IGNORECASE)
|
|
81
|
+
if m_code:
|
|
82
|
+
try:
|
|
83
|
+
return json.loads(m_code.group(1).strip())
|
|
84
|
+
except Exception:
|
|
85
|
+
pass
|
|
86
|
+
|
|
87
|
+
# 2. Try outermost curly braces
|
|
88
|
+
m_brace = re.search(r"\{[\s\S]*\}", clean)
|
|
89
|
+
if m_brace:
|
|
90
|
+
try:
|
|
91
|
+
return json.loads(m_brace.group(0).strip())
|
|
92
|
+
except Exception:
|
|
93
|
+
pass
|
|
94
|
+
|
|
95
|
+
# 3. Direct parse
|
|
96
|
+
return json.loads(clean)
|
|
97
|
+
|
|
98
|
+
|
|
34
99
|
class LLMClient:
|
|
35
100
|
"""OpenAI-compatible client with standard host, token, context size, and model configuration."""
|
|
36
101
|
|
|
@@ -59,7 +124,6 @@ class LLMClient:
|
|
|
59
124
|
if self._ping_url(self.base_url):
|
|
60
125
|
return True
|
|
61
126
|
|
|
62
|
-
# If the user explicitly passed a host/base_url, never overwrite it with default WSL fallback
|
|
63
127
|
if self.user_specified_host:
|
|
64
128
|
return False
|
|
65
129
|
|
|
@@ -191,7 +255,7 @@ class LLMClient:
|
|
|
191
255
|
) -> Dict[str, str]:
|
|
192
256
|
"""Generate concise explanations for a symbol in JSON format in the requested natural language."""
|
|
193
257
|
prompt = f"""Please analyze the following {lang} symbol `{name}` ({kind}) and output concise design intent and specifications in JSON format.
|
|
194
|
-
Output Language: {language} (Write all text
|
|
258
|
+
Output Language: {language} (Write all explanation text in {language}).
|
|
195
259
|
Be concise and avoid repetition.
|
|
196
260
|
|
|
197
261
|
### Signature / Type:
|
|
@@ -213,12 +277,12 @@ Be concise and avoid repetition.
|
|
|
213
277
|
{code}
|
|
214
278
|
```
|
|
215
279
|
|
|
216
|
-
Return ONLY a valid JSON object
|
|
280
|
+
Return ONLY a valid JSON object matching these keys (values written in {language}):
|
|
217
281
|
{{
|
|
218
|
-
"purpose": "Core design intent and purpose (1-2 concise sentences)",
|
|
282
|
+
"purpose": "Core design intent and purpose (1-2 concise sentences in {language})",
|
|
219
283
|
"inputs": "Input parameters description (or None)",
|
|
220
284
|
"outputs": "Return value or side effects description",
|
|
221
|
-
"overview": "Concise summary of implementation and role (1-3 sentences)"
|
|
285
|
+
"overview": "Concise summary of implementation and role (1-3 sentences in {language})"
|
|
222
286
|
}}
|
|
223
287
|
"""
|
|
224
288
|
messages = [
|
|
@@ -227,19 +291,18 @@ Return ONLY a valid JSON object (all string values in {language}):
|
|
|
227
291
|
]
|
|
228
292
|
|
|
229
293
|
try:
|
|
230
|
-
raw_res = self.chat_completion(messages, json_mode=
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
return json.loads(m.group(0))
|
|
234
|
-
return json.loads(raw_res)
|
|
294
|
+
raw_res = self.chat_completion(messages, json_mode=False, max_tokens=768, timeout=60)
|
|
295
|
+
parsed = extract_json_from_text(raw_res)
|
|
296
|
+
return normalize_llm_json_dict(parsed)
|
|
235
297
|
except Exception as e:
|
|
236
298
|
if not allow_fallback:
|
|
237
299
|
raise LLMError(f"Failed to analyze symbol `{name}`: {e}") from e
|
|
300
|
+
is_ja = language in ("Japanese", "日本語")
|
|
238
301
|
return {
|
|
239
|
-
"purpose": f"Executes `{name}` operations.",
|
|
240
|
-
"inputs": "Accepts input parameters.",
|
|
241
|
-
"outputs": "Returns result value.",
|
|
242
|
-
"overview": f"Basic operation for `{name}`.",
|
|
302
|
+
"purpose": f"`{name}` の処理を実行する。" if is_ja else f"Executes `{name}` operations.",
|
|
303
|
+
"inputs": "パラメータを受け取る。" if is_ja else "Accepts input parameters.",
|
|
304
|
+
"outputs": "結果値を返す。" if is_ja else "Returns result value.",
|
|
305
|
+
"overview": f"`{name}` の基本処理。" if is_ja else f"Basic operation for `{name}`.",
|
|
243
306
|
}
|
|
244
307
|
|
|
245
308
|
def refine_variable_top_down(
|
|
@@ -283,16 +346,15 @@ Return ONLY a valid JSON object (all string values in {language}):
|
|
|
283
346
|
]
|
|
284
347
|
|
|
285
348
|
try:
|
|
286
|
-
raw_res = self.chat_completion(messages, json_mode=
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
return json.loads(m.group(0))
|
|
290
|
-
return json.loads(raw_res)
|
|
349
|
+
raw_res = self.chat_completion(messages, json_mode=False, max_tokens=768, timeout=60)
|
|
350
|
+
parsed = extract_json_from_text(raw_res)
|
|
351
|
+
return normalize_llm_json_dict(parsed)
|
|
291
352
|
except Exception as e:
|
|
292
353
|
if not allow_fallback:
|
|
293
354
|
raise LLMError(f"Failed top-down variable refinement for `{var_name}`: {e}") from e
|
|
355
|
+
is_ja = language in ("Japanese", "日本語")
|
|
294
356
|
return {
|
|
295
|
-
"significance": f"`{var_name}` is a state/data utilized by callers.",
|
|
296
|
-
"usage_scenario": "Passed and transformed across calling functions.",
|
|
297
|
-
"top_down_summary": f"Design summary for `{var_name}`.",
|
|
357
|
+
"significance": f"`{var_name}` は呼び出し元で使用される状態/データ。" if is_ja else f"`{var_name}` is a state/data utilized by callers.",
|
|
358
|
+
"usage_scenario": "呼び出し元関数間で受け渡される。" if is_ja else "Passed and transformed across calling functions.",
|
|
359
|
+
"top_down_summary": f"`{var_name}` の設計概要。" if is_ja else f"Design summary for `{var_name}`.",
|
|
298
360
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pystdoc
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator.
|
|
5
5
|
Author: tab4moji
|
|
6
6
|
License: MIT
|
|
@@ -142,7 +142,7 @@ class TestDocgen(unittest.TestCase):
|
|
|
142
142
|
)
|
|
143
143
|
self.assertEqual(res_en, 0)
|
|
144
144
|
doc_en = (self.test_dir / ".docgen" / "documents" / "src" / "sample.c.md").read_text(encoding="utf-8")
|
|
145
|
-
self.assertIn("## 1.
|
|
145
|
+
self.assertIn("## 1. Top-Down Architectural Context & Role", doc_en)
|
|
146
146
|
|
|
147
147
|
# Japanese option
|
|
148
148
|
res_ja = run_docgen(
|
|
@@ -154,7 +154,7 @@ class TestDocgen(unittest.TestCase):
|
|
|
154
154
|
)
|
|
155
155
|
self.assertEqual(res_ja, 0)
|
|
156
156
|
doc_ja = (self.test_dir / ".docgen" / "documents" / "src" / "sample.c.md").read_text(encoding="utf-8")
|
|
157
|
-
self.assertIn("## 1.
|
|
157
|
+
self.assertIn("## 1. Top-Down Architectural Context & Role", doc_ja)
|
|
158
158
|
|
|
159
159
|
def test_llm_client_host_and_token(self):
|
|
160
160
|
self.assertEqual(normalize_host_url("127.0.0.1:11434"), "http://127.0.0.1:11434/v1")
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|