pystdoc 0.8.2__tar.gz → 0.8.3__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.8.2/src/pystdoc.egg-info → pystdoc-0.8.3}/PKG-INFO +1 -1
- {pystdoc-0.8.2 → pystdoc-0.8.3}/pyproject.toml +1 -1
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/__init__.py +1 -1
- pystdoc-0.8.3/src/pystdoc/doc_labels.py +171 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/doc_writer.py +144 -47
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/engine.py +14 -1
- {pystdoc-0.8.2 → pystdoc-0.8.3/src/pystdoc.egg-info}/PKG-INFO +1 -1
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/SOURCES.txt +2 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_config.py +91 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_docgen.py +15 -2
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_live_server_100.py +2 -2
- pystdoc-0.8.3/tests/test_real_litert_server.py +240 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/LICENSE +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/README.md +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/setup.cfg +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/__main__.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/__init__.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/base.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/clang_adapter.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/generic_adapter.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/java_adapter.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/kotlin_adapter.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/python_adapter.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/cache.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/call_graph.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/cli.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/compilation_db.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/config.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/db.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/design_engine.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/hasher.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/interrupt.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/llm_client.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/mcp_server.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_clang.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_generic.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_java.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_kotlin.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_python.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/perf.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/progress.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/query.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/report_engine.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/scanner.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/similarity.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/symbols.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/ui_detector.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/watcher.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/dependency_links.txt +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/entry_points.txt +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/requires.txt +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/top_level.txt +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_adapters.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_cli.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_coverage_boost.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_design_engine_full.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_designgen.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_engine.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_engine_full.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_final_100.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_interrupt.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_llm_client.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_mcp_server.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_parser_generic.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_parser_java.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_parser_kotlin.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_pep8.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_perf.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_progress.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_query.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_reduce_cache.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_reportgen.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_ui_detector.py +0 -0
- {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_watcher.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pystdoc
|
|
3
|
-
Version: 0.8.
|
|
3
|
+
Version: 0.8.3
|
|
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.8.
|
|
7
|
+
version = "0.8.3"
|
|
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 = [
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
"""Documentation label localization and JSON template management."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Any, Dict, Optional
|
|
6
|
+
|
|
7
|
+
DEFAULT_ENGLISH_LABELS: Dict[str, str] = {
|
|
8
|
+
"language": "English",
|
|
9
|
+
"doc_title_template": "{kind} Documentation: `{name}`",
|
|
10
|
+
"basic_info_title": "## 1. Basic Information",
|
|
11
|
+
"label_name": "Name",
|
|
12
|
+
"label_fqdn": "FQDN",
|
|
13
|
+
"label_symbol_kind": "Symbol Kind",
|
|
14
|
+
"label_location": "Location",
|
|
15
|
+
"location_template": "Line {start} to Line {end}",
|
|
16
|
+
"label_signature": "Signature / Type",
|
|
17
|
+
"parameters_title": "## 2. Parameters",
|
|
18
|
+
"label_none": "None",
|
|
19
|
+
"input_return_title": "## 3. Input / Return Specifications",
|
|
20
|
+
"label_input_constraints": "Input Constraints",
|
|
21
|
+
"label_return_type": "Return Type",
|
|
22
|
+
"label_return_value_side_effects": "Return Value & Side Effects",
|
|
23
|
+
"label_void_none": "void / None",
|
|
24
|
+
"called_functions_title": "## 4. Called Functions",
|
|
25
|
+
"referencing_functions_title": "## 4. Referencing Functions",
|
|
26
|
+
"source_code_snippet_title": "## Source Code Snippet",
|
|
27
|
+
"file_doc_title_template": "File Documentation: `{path}`",
|
|
28
|
+
"label_file_hash": "File SHA-256",
|
|
29
|
+
"label_detected_symbols": "Detected Symbols",
|
|
30
|
+
"symbol_list_title": "## Symbol List",
|
|
31
|
+
"symbol_list_item_template": "- `{name}` ({kind}) [Lines: {line_range}]",
|
|
32
|
+
"kind_function": "Function",
|
|
33
|
+
"kind_class": "Class",
|
|
34
|
+
"kind_method": "Method",
|
|
35
|
+
"kind_variable": "Variable",
|
|
36
|
+
"kind_struct": "Struct",
|
|
37
|
+
"kind_enum": "Enum",
|
|
38
|
+
"kind_interface": "Interface",
|
|
39
|
+
"kind_constant": "Constant",
|
|
40
|
+
"kind_type": "Type",
|
|
41
|
+
"kind_module": "Module",
|
|
42
|
+
"prose_referenced_by_template": (
|
|
43
|
+
"In the system architecture, it is referenced by {callers}."
|
|
44
|
+
),
|
|
45
|
+
"prose_root_entry_point": (
|
|
46
|
+
"It serves as the root entry point (system bootstrap and dispatcher)."
|
|
47
|
+
),
|
|
48
|
+
"prose_implementation_overview_template": (
|
|
49
|
+
"Implementation overview: {overview}"
|
|
50
|
+
),
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def get_default_labels(language: str = "English") -> Dict[str, str]:
|
|
55
|
+
"""Return default dictionary of documentation labels (English base)."""
|
|
56
|
+
return dict(DEFAULT_ENGLISH_LABELS)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def translate_labels_with_llm(
|
|
60
|
+
llm_client: Any,
|
|
61
|
+
target_language: str,
|
|
62
|
+
) -> Dict[str, str]:
|
|
63
|
+
"""Translate documentation labels to target_language using LLM."""
|
|
64
|
+
from pystdoc.llm_client import extract_json_from_text
|
|
65
|
+
|
|
66
|
+
base_labels = dict(DEFAULT_ENGLISH_LABELS)
|
|
67
|
+
base_labels["language"] = target_language
|
|
68
|
+
|
|
69
|
+
system_prompt = (
|
|
70
|
+
"You are an expert technical documentation localizer. "
|
|
71
|
+
f"Translate software documentation labels and headings into natural, "
|
|
72
|
+
f"standard software engineering terms in {target_language}.\n"
|
|
73
|
+
"Guidelines:\n"
|
|
74
|
+
"- In Japanese software engineering, documentation is conventionally "
|
|
75
|
+
"called '仕様書' (e.g. '関数仕様書' for Function Documentation, "
|
|
76
|
+
"'クラス仕様書' for Class Documentation, "
|
|
77
|
+
"'ファイル仕様書' for File Documentation).\n"
|
|
78
|
+
"- When translating into Japanese, translate `doc_title_template` "
|
|
79
|
+
"as '{kind}仕様書: `{name}`', `file_doc_title_template` as "
|
|
80
|
+
"'ファイル仕様書: `{path}`', `kind_function` as '関数', "
|
|
81
|
+
"`kind_class` as 'クラス', `kind_method` as 'メソッド', "
|
|
82
|
+
"`kind_variable` as '変数', `kind_struct` as '構造体', "
|
|
83
|
+
"`kind_enum` as '列挙型', `kind_constant` as '定数'.\n"
|
|
84
|
+
"- For other languages, translate software terms idiomatic to that "
|
|
85
|
+
"language (e.g. Funktion in German, 函数 in Chinese).\n"
|
|
86
|
+
"- Keep placeholders {kind}, {name}, {path}, {start}, {end}, "
|
|
87
|
+
"{line_range}, {callers}, {overview} exactly as is.\n"
|
|
88
|
+
"- Respond strictly with a valid JSON object matching the input keys."
|
|
89
|
+
)
|
|
90
|
+
user_prompt = (
|
|
91
|
+
f"Translate the following JSON documentation labels into "
|
|
92
|
+
f"{target_language}:\n\n"
|
|
93
|
+
f"```json\n"
|
|
94
|
+
f"{json.dumps(base_labels, indent=2, ensure_ascii=False)}\n"
|
|
95
|
+
f"```\n\n"
|
|
96
|
+
f"Output ONLY valid JSON."
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
try:
|
|
100
|
+
messages = [
|
|
101
|
+
{"role": "system", "content": system_prompt},
|
|
102
|
+
{"role": "user", "content": user_prompt},
|
|
103
|
+
]
|
|
104
|
+
response_text = llm_client.chat_completion(messages)
|
|
105
|
+
parsed = extract_json_from_text(response_text)
|
|
106
|
+
if isinstance(parsed, dict) and len(parsed) >= 5:
|
|
107
|
+
merged = dict(base_labels)
|
|
108
|
+
for k, v in parsed.items():
|
|
109
|
+
if k in merged and isinstance(v, str) and v.strip():
|
|
110
|
+
merged[k] = v.strip()
|
|
111
|
+
merged["language"] = target_language
|
|
112
|
+
return merged
|
|
113
|
+
except Exception:
|
|
114
|
+
pass
|
|
115
|
+
|
|
116
|
+
return base_labels
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def get_or_init_document_labels(
|
|
120
|
+
target_dir: Optional[Path],
|
|
121
|
+
language: str = "English",
|
|
122
|
+
llm_client: Optional[Any] = None,
|
|
123
|
+
) -> Dict[str, str]:
|
|
124
|
+
"""Load or initialize document_labels.json under target_dir/.pystdoc/."""
|
|
125
|
+
from pystdoc.doc_writer import normalize_language
|
|
126
|
+
|
|
127
|
+
norm_lang = normalize_language(language)
|
|
128
|
+
defaults = get_default_labels(norm_lang)
|
|
129
|
+
|
|
130
|
+
if target_dir is None:
|
|
131
|
+
return defaults
|
|
132
|
+
|
|
133
|
+
pystdoc_dir = target_dir / ".pystdoc"
|
|
134
|
+
labels_file = pystdoc_dir / "document_labels.json"
|
|
135
|
+
|
|
136
|
+
if labels_file.exists():
|
|
137
|
+
try:
|
|
138
|
+
content = labels_file.read_text(encoding="utf-8")
|
|
139
|
+
loaded = json.loads(content)
|
|
140
|
+
if (
|
|
141
|
+
isinstance(loaded, dict)
|
|
142
|
+
and loaded.get("language") == norm_lang
|
|
143
|
+
):
|
|
144
|
+
merged = dict(defaults)
|
|
145
|
+
merged.update(loaded)
|
|
146
|
+
return merged
|
|
147
|
+
except Exception:
|
|
148
|
+
pass
|
|
149
|
+
|
|
150
|
+
# If language is not English, generate localized labels via LLM
|
|
151
|
+
final_labels = defaults
|
|
152
|
+
if norm_lang != "English" and llm_client is not None:
|
|
153
|
+
try:
|
|
154
|
+
print(
|
|
155
|
+
f"[Labels] Generating localized document labels for "
|
|
156
|
+
f"{norm_lang} via LLM...",
|
|
157
|
+
flush=True,
|
|
158
|
+
)
|
|
159
|
+
final_labels = translate_labels_with_llm(llm_client, norm_lang)
|
|
160
|
+
except Exception:
|
|
161
|
+
final_labels = defaults
|
|
162
|
+
|
|
163
|
+
# Save initial labels JSON for the target language
|
|
164
|
+
try:
|
|
165
|
+
pystdoc_dir.mkdir(parents=True, exist_ok=True)
|
|
166
|
+
content = json.dumps(final_labels, indent=2, ensure_ascii=False) + "\n"
|
|
167
|
+
labels_file.write_text(content, encoding="utf-8")
|
|
168
|
+
except Exception:
|
|
169
|
+
pass
|
|
170
|
+
|
|
171
|
+
return final_labels
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
"""Markdown doc generator for symbols with layout & language support."""
|
|
2
2
|
|
|
3
3
|
from pathlib import Path
|
|
4
|
-
from typing import List, Optional
|
|
4
|
+
from typing import Dict, List, Optional
|
|
5
5
|
|
|
6
6
|
from pystdoc.adapters import get_default_registry
|
|
7
7
|
from pystdoc.cache import write_flushed_text
|
|
8
8
|
from pystdoc.compilation_db import CompilationDatabase
|
|
9
|
+
from pystdoc.doc_labels import get_default_labels, get_or_init_document_labels
|
|
9
10
|
from pystdoc.parser_clang import parse_clang_file
|
|
10
11
|
from pystdoc.parser_generic import parse_generic_file
|
|
11
12
|
from pystdoc.parser_java import parse_java_file
|
|
@@ -99,15 +100,21 @@ def format_symbol_section(
|
|
|
99
100
|
file_path: Path,
|
|
100
101
|
level: int = 2,
|
|
101
102
|
language: str = "English",
|
|
103
|
+
labels: Optional[Dict[str, str]] = None,
|
|
102
104
|
) -> str:
|
|
103
105
|
"""Format symbol doc with Top-Down first, followed by Bottom-Up."""
|
|
104
106
|
norm_lang = normalize_language(language)
|
|
107
|
+
if labels is None:
|
|
108
|
+
labels = get_default_labels(norm_lang)
|
|
105
109
|
is_ja = norm_lang == "Japanese"
|
|
106
110
|
|
|
107
111
|
h_prefix = "#" * level
|
|
108
|
-
|
|
112
|
+
kind_lower = sym.kind.lower()
|
|
113
|
+
kind_key = f"kind_{kind_lower}"
|
|
114
|
+
kind_display_name = labels.get(kind_key, sym.kind.capitalize())
|
|
115
|
+
kind_display = kind_display_name
|
|
109
116
|
if sym.fqdn:
|
|
110
|
-
kind_display = f"{
|
|
117
|
+
kind_display = f"{kind_display_name} (FQDN: `{sym.fqdn}`)"
|
|
111
118
|
|
|
112
119
|
snippet = get_code_snippet(file_path, sym.line_start, sym.line_end)
|
|
113
120
|
lang_id = get_code_language(file_path.suffix)
|
|
@@ -176,26 +183,29 @@ def format_symbol_section(
|
|
|
176
183
|
if is_ja
|
|
177
184
|
else ", ".join(sym.referencing_functions)
|
|
178
185
|
)
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
f"{callers_str}."
|
|
186
|
+
tmpl_ref = labels.get("prose_referenced_by_template")
|
|
187
|
+
eng_ref = "In the system architecture, it is referenced by {callers}."
|
|
188
|
+
if not tmpl_ref or (is_ja and tmpl_ref == eng_ref):
|
|
189
|
+
tmpl_ref = (
|
|
190
|
+
"上位モジュールからは、{callers} などの目的で利用・参照されます。"
|
|
191
|
+
if is_ja
|
|
192
|
+
else eng_ref
|
|
187
193
|
)
|
|
194
|
+
prose_sentences.append(tmpl_ref.format(callers=callers_str))
|
|
188
195
|
elif sym.name in ("main", "app", "cli", "run"):
|
|
189
|
-
|
|
190
|
-
|
|
196
|
+
prose_root = labels.get("prose_root_entry_point")
|
|
197
|
+
eng_root = (
|
|
198
|
+
"It serves as the root entry point (system bootstrap and "
|
|
199
|
+
"dispatcher)."
|
|
200
|
+
)
|
|
201
|
+
if not prose_root or (is_ja and prose_root == eng_root):
|
|
202
|
+
prose_root = (
|
|
191
203
|
"プログラムの最上位エントリーポイント(起動・全体統括)として"
|
|
192
204
|
"位置付けられています。"
|
|
205
|
+
if is_ja
|
|
206
|
+
else eng_root
|
|
193
207
|
)
|
|
194
|
-
|
|
195
|
-
prose_sentences.append(
|
|
196
|
-
"It serves as the root entry point (system bootstrap and "
|
|
197
|
-
"dispatcher)."
|
|
198
|
-
)
|
|
208
|
+
prose_sentences.append(prose_root)
|
|
199
209
|
|
|
200
210
|
prose_sentences.append(
|
|
201
211
|
data_flow_desc.rstrip("。.") + ("。" if is_ja else ".")
|
|
@@ -206,59 +216,116 @@ def format_symbol_section(
|
|
|
206
216
|
and sym.overview != sym.purpose
|
|
207
217
|
and sym.overview != role_desc
|
|
208
218
|
):
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
219
|
+
tmpl_ov = labels.get("prose_implementation_overview_template")
|
|
220
|
+
eng_ov = "Implementation overview: {overview}"
|
|
221
|
+
if not tmpl_ov or (is_ja and tmpl_ov == eng_ov):
|
|
222
|
+
tmpl_ov = (
|
|
223
|
+
"実装面では、{overview}"
|
|
224
|
+
if is_ja
|
|
225
|
+
else eng_ov
|
|
214
226
|
)
|
|
227
|
+
prose_sentences.append(tmpl_ov.format(overview=sym.overview))
|
|
215
228
|
|
|
216
229
|
prose_paragraph = " ".join(prose_sentences)
|
|
217
230
|
|
|
231
|
+
doc_title_tmpl = labels.get(
|
|
232
|
+
"doc_title_template", "{kind} Documentation: `{name}`"
|
|
233
|
+
)
|
|
234
|
+
doc_title = doc_title_tmpl.format(
|
|
235
|
+
kind=kind_display_name, name=sym.name
|
|
236
|
+
)
|
|
237
|
+
# Ensure natural Japanese phrasing without awkward space (e.g. '関数仕様書')
|
|
238
|
+
if is_ja and f"{kind_display_name} 仕様書" in doc_title:
|
|
239
|
+
doc_title = doc_title.replace(
|
|
240
|
+
f"{kind_display_name} 仕様書", f"{kind_display_name}仕様書"
|
|
241
|
+
)
|
|
242
|
+
for eng_kind, ja_kind in (
|
|
243
|
+
("Function", "関数"),
|
|
244
|
+
("Class", "クラス"),
|
|
245
|
+
("Method", "メソッド"),
|
|
246
|
+
("Variable", "変数"),
|
|
247
|
+
("Struct", "構造体"),
|
|
248
|
+
("Enum", "列挙型"),
|
|
249
|
+
):
|
|
250
|
+
if is_ja and f"{eng_kind} 仕様書" in doc_title:
|
|
251
|
+
doc_title = doc_title.replace(
|
|
252
|
+
f"{eng_kind} 仕様書", f"{ja_kind}仕様書"
|
|
253
|
+
)
|
|
254
|
+
elif is_ja and f"{eng_kind}仕様書" in doc_title:
|
|
255
|
+
doc_title = doc_title.replace(
|
|
256
|
+
f"{eng_kind}仕様書", f"{ja_kind}仕様書"
|
|
257
|
+
)
|
|
258
|
+
|
|
259
|
+
loc_tmpl = labels.get("location_template", "Line {start} to Line {end}")
|
|
260
|
+
loc_str = loc_tmpl.format(start=sym.line_start, end=sym.line_end)
|
|
261
|
+
|
|
218
262
|
lines = [
|
|
219
|
-
f"{h_prefix} {
|
|
263
|
+
f"{h_prefix} {doc_title}",
|
|
220
264
|
"",
|
|
221
265
|
prose_paragraph,
|
|
222
266
|
"",
|
|
223
|
-
"## 1. Basic Information",
|
|
224
|
-
f"- **
|
|
225
|
-
f"
|
|
226
|
-
f"- **Symbol Kind**:
|
|
227
|
-
f"
|
|
267
|
+
labels.get("basic_info_title", "## 1. Basic Information"),
|
|
268
|
+
f"- **{labels.get('label_fqdn', 'FQDN')}**: "
|
|
269
|
+
f"`{sym.fqdn or sym.name}`",
|
|
270
|
+
f"- **{labels.get('label_symbol_kind', 'Symbol Kind')}**: "
|
|
271
|
+
f"`{kind_display}`",
|
|
272
|
+
f"- **{labels.get('label_location', 'Location')}**: {loc_str}",
|
|
228
273
|
]
|
|
229
274
|
if sym.signature:
|
|
230
|
-
|
|
275
|
+
sig_lbl = labels.get("label_signature", "Signature / Type")
|
|
276
|
+
lines.append(f"- **{sig_lbl}**: `{sym.signature}`")
|
|
231
277
|
|
|
278
|
+
param_title = labels.get("parameters_title", "## 2. Parameters")
|
|
279
|
+
none_lbl = labels.get("label_none", "None")
|
|
232
280
|
if sym.parameters:
|
|
233
|
-
lines.extend(["",
|
|
281
|
+
lines.extend(["", param_title])
|
|
234
282
|
for p in sym.parameters:
|
|
235
283
|
p_type = f": `{p.type_hint}`" if p.type_hint else ""
|
|
236
284
|
lines.append(f"- `{p.name}`{p_type}")
|
|
237
285
|
else:
|
|
238
|
-
lines.extend(["",
|
|
286
|
+
lines.extend(["", param_title, f"- {none_lbl}"])
|
|
239
287
|
|
|
240
288
|
if sym.return_type or sym.outputs_note or sym.inputs_note:
|
|
241
|
-
|
|
289
|
+
input_ret_title = labels.get(
|
|
290
|
+
"input_return_title", "## 3. Input / Return Specifications"
|
|
291
|
+
)
|
|
292
|
+
lines.extend(["", input_ret_title])
|
|
242
293
|
if sym.inputs_note:
|
|
243
|
-
|
|
244
|
-
|
|
294
|
+
in_lbl = labels.get("label_input_constraints", "Input Constraints")
|
|
295
|
+
lines.append(f"- {in_lbl}: {sym.inputs_note}")
|
|
296
|
+
void_lbl = labels.get("label_void_none", "void / None")
|
|
297
|
+
ret_lbl = labels.get("label_return_type", "Return Type")
|
|
298
|
+
lines.append(f"- {ret_lbl}: `{sym.return_type or void_lbl}`")
|
|
245
299
|
if sym.outputs_note:
|
|
246
|
-
|
|
300
|
+
out_lbl = labels.get(
|
|
301
|
+
"label_return_value_side_effects",
|
|
302
|
+
"Return Value & Side Effects",
|
|
303
|
+
)
|
|
304
|
+
lines.append(f"- {out_lbl}: {sym.outputs_note}")
|
|
247
305
|
|
|
248
306
|
if sym.callees:
|
|
249
|
-
|
|
307
|
+
callees_title = labels.get(
|
|
308
|
+
"called_functions_title", "## 4. Called Functions"
|
|
309
|
+
)
|
|
310
|
+
lines.extend(["", callees_title])
|
|
250
311
|
for c in sym.callees:
|
|
251
312
|
lines.append(f"- `{c}`")
|
|
252
313
|
elif sym.referencing_functions:
|
|
253
|
-
|
|
314
|
+
refs_title = labels.get(
|
|
315
|
+
"referencing_functions_title", "## 4. Referencing Functions"
|
|
316
|
+
)
|
|
317
|
+
lines.extend(["", refs_title])
|
|
254
318
|
for r in sym.referencing_functions:
|
|
255
319
|
lines.append(f"- {r}")
|
|
256
320
|
|
|
257
321
|
if snippet:
|
|
322
|
+
src_title = labels.get(
|
|
323
|
+
"source_code_snippet_title", "## Source Code Snippet"
|
|
324
|
+
)
|
|
258
325
|
lines.extend(
|
|
259
326
|
[
|
|
260
327
|
"",
|
|
261
|
-
|
|
328
|
+
src_title,
|
|
262
329
|
f"```{lang_id}",
|
|
263
330
|
snippet,
|
|
264
331
|
"```",
|
|
@@ -270,7 +337,11 @@ def format_symbol_section(
|
|
|
270
337
|
for child in sym.children:
|
|
271
338
|
lines.append(
|
|
272
339
|
format_symbol_section(
|
|
273
|
-
child,
|
|
340
|
+
child,
|
|
341
|
+
file_path,
|
|
342
|
+
level=level + 1,
|
|
343
|
+
language=norm_lang,
|
|
344
|
+
labels=labels,
|
|
274
345
|
)
|
|
275
346
|
)
|
|
276
347
|
|
|
@@ -284,9 +355,12 @@ def write_single_symbol_doc(
|
|
|
284
355
|
prefix_name: str = "",
|
|
285
356
|
language: str = "English",
|
|
286
357
|
symbol_id_override: Optional[str] = None,
|
|
358
|
+
labels: Optional[Dict[str, str]] = None,
|
|
287
359
|
) -> Path:
|
|
288
360
|
"""Write an individual symbol document with immediate flush."""
|
|
289
361
|
norm_lang = normalize_language(language)
|
|
362
|
+
if labels is None:
|
|
363
|
+
labels = get_or_init_document_labels(target_dir, norm_lang)
|
|
290
364
|
pystdoc_dir = target_dir / ".pystdoc" / "documents"
|
|
291
365
|
pystdoc_dir.mkdir(parents=True, exist_ok=True)
|
|
292
366
|
|
|
@@ -300,7 +374,7 @@ def write_single_symbol_doc(
|
|
|
300
374
|
|
|
301
375
|
full_path = target_dir / rel_path
|
|
302
376
|
content = format_symbol_section(
|
|
303
|
-
symbol, full_path, level=1, language=norm_lang
|
|
377
|
+
symbol, full_path, level=1, language=norm_lang, labels=labels
|
|
304
378
|
)
|
|
305
379
|
|
|
306
380
|
write_flushed_text(out_file, content + "\n")
|
|
@@ -313,9 +387,12 @@ def write_individual_symbol_docs(
|
|
|
313
387
|
symbols: List[Symbol],
|
|
314
388
|
prefix_name: str = "",
|
|
315
389
|
language: str = "English",
|
|
390
|
+
labels: Optional[Dict[str, str]] = None,
|
|
316
391
|
) -> List[Path]:
|
|
317
392
|
"""Recursively write docs for each symbol with immediate flush."""
|
|
318
393
|
norm_lang = normalize_language(language)
|
|
394
|
+
if labels is None:
|
|
395
|
+
labels = get_or_init_document_labels(target_dir, norm_lang)
|
|
319
396
|
created_files: List[Path] = []
|
|
320
397
|
|
|
321
398
|
for sym in symbols:
|
|
@@ -325,6 +402,7 @@ def write_individual_symbol_docs(
|
|
|
325
402
|
sym,
|
|
326
403
|
prefix_name=prefix_name,
|
|
327
404
|
language=norm_lang,
|
|
405
|
+
labels=labels,
|
|
328
406
|
)
|
|
329
407
|
created_files.append(out_file)
|
|
330
408
|
|
|
@@ -338,6 +416,7 @@ def write_individual_symbol_docs(
|
|
|
338
416
|
sym.children,
|
|
339
417
|
prefix_name=child_prefix,
|
|
340
418
|
language=norm_lang,
|
|
419
|
+
labels=labels,
|
|
341
420
|
)
|
|
342
421
|
created_files.extend(child_files)
|
|
343
422
|
|
|
@@ -350,34 +429,52 @@ def write_symbol_doc(
|
|
|
350
429
|
file_hash: str,
|
|
351
430
|
symbols: List[Symbol],
|
|
352
431
|
language: str = "English",
|
|
432
|
+
labels: Optional[Dict[str, str]] = None,
|
|
353
433
|
) -> Path:
|
|
354
434
|
"""Write comprehensive file documentation with immediate flush."""
|
|
355
435
|
norm_lang = normalize_language(language)
|
|
436
|
+
if labels is None:
|
|
437
|
+
labels = get_or_init_document_labels(target_dir, norm_lang)
|
|
356
438
|
pystdoc_dir = target_dir / ".pystdoc" / "documents"
|
|
357
439
|
pystdoc_dir.mkdir(parents=True, exist_ok=True)
|
|
358
440
|
|
|
359
441
|
out_file = pystdoc_dir / f"{rel_path.as_posix()}.md"
|
|
360
442
|
full_path = target_dir / rel_path
|
|
361
443
|
|
|
444
|
+
title_fmt = labels.get(
|
|
445
|
+
"file_doc_title_template", "File Documentation: `{path}`"
|
|
446
|
+
)
|
|
362
447
|
lines = [
|
|
363
|
-
f"#
|
|
448
|
+
f"# {title_fmt.format(path=rel_path.as_posix())}",
|
|
364
449
|
"",
|
|
365
|
-
f"- **File SHA-256**:
|
|
366
|
-
f"
|
|
450
|
+
f"- **{labels.get('label_file_hash', 'File SHA-256')}**: "
|
|
451
|
+
f"`{file_hash}`",
|
|
452
|
+
f"- **{labels.get('label_detected_symbols', 'Detected Symbols')}**: "
|
|
453
|
+
f"{len(symbols)}",
|
|
367
454
|
"",
|
|
368
|
-
"## Symbol List",
|
|
455
|
+
labels.get("symbol_list_title", "## Symbol List"),
|
|
369
456
|
]
|
|
370
457
|
|
|
458
|
+
item_tmpl = labels.get(
|
|
459
|
+
"symbol_list_item_template",
|
|
460
|
+
"- `{name}` ({kind}) [Lines: {line_range}]",
|
|
461
|
+
)
|
|
371
462
|
for sym in symbols:
|
|
372
463
|
line_range = f"{sym.line_start}-{sym.line_end}"
|
|
464
|
+
k_key = f"kind_{sym.kind.lower()}"
|
|
465
|
+
k_name = labels.get(k_key, sym.kind)
|
|
373
466
|
lines.append(
|
|
374
|
-
|
|
467
|
+
item_tmpl.format(
|
|
468
|
+
name=sym.name, kind=k_name, line_range=line_range
|
|
469
|
+
)
|
|
375
470
|
)
|
|
376
471
|
|
|
377
472
|
lines.append("")
|
|
378
473
|
for sym in symbols:
|
|
379
474
|
lines.append(
|
|
380
|
-
format_symbol_section(
|
|
475
|
+
format_symbol_section(
|
|
476
|
+
sym, full_path, level=2, language=norm_lang, labels=labels
|
|
477
|
+
)
|
|
381
478
|
)
|
|
382
479
|
lines.append("")
|
|
383
480
|
|
|
@@ -28,6 +28,7 @@ from pystdoc.doc_writer import (
|
|
|
28
28
|
write_individual_symbol_docs,
|
|
29
29
|
normalize_language,
|
|
30
30
|
)
|
|
31
|
+
from pystdoc.doc_labels import get_or_init_document_labels
|
|
31
32
|
from pystdoc.llm_client import (
|
|
32
33
|
LLMClient,
|
|
33
34
|
sanitize_architectural_context,
|
|
@@ -494,6 +495,10 @@ def run_docgen(
|
|
|
494
495
|
db.close()
|
|
495
496
|
return 1
|
|
496
497
|
|
|
498
|
+
doc_labels = get_or_init_document_labels(
|
|
499
|
+
target_dir, norm_lang, llm_client=llm_client
|
|
500
|
+
)
|
|
501
|
+
|
|
497
502
|
# 1. Scan files
|
|
498
503
|
matched_files = scan_files(target_dir)
|
|
499
504
|
files_txt = write_files_list(target_dir, matched_files)
|
|
@@ -966,6 +971,7 @@ def run_docgen(
|
|
|
966
971
|
prefix_name=prefix_in_unique_id,
|
|
967
972
|
language=norm_lang,
|
|
968
973
|
symbol_id_override=raw_id if raw_id else None,
|
|
974
|
+
labels=doc_labels,
|
|
969
975
|
)
|
|
970
976
|
|
|
971
977
|
# Persist latest hash and metadata to SQLite
|
|
@@ -1305,6 +1311,7 @@ def run_docgen(
|
|
|
1305
1311
|
v_sym,
|
|
1306
1312
|
prefix_name=prefix_in_unique_id,
|
|
1307
1313
|
language=norm_lang,
|
|
1314
|
+
labels=doc_labels,
|
|
1308
1315
|
)
|
|
1309
1316
|
else:
|
|
1310
1317
|
with var_rem_lock:
|
|
@@ -1342,6 +1349,7 @@ def run_docgen(
|
|
|
1342
1349
|
v_sym,
|
|
1343
1350
|
prefix_name=prefix_in_unique_id,
|
|
1344
1351
|
language=norm_lang,
|
|
1352
|
+
labels=doc_labels,
|
|
1345
1353
|
)
|
|
1346
1354
|
|
|
1347
1355
|
if var_nodes:
|
|
@@ -1421,9 +1429,14 @@ def run_docgen(
|
|
|
1421
1429
|
current_hash,
|
|
1422
1430
|
symbols,
|
|
1423
1431
|
language=norm_lang,
|
|
1432
|
+
labels=doc_labels,
|
|
1424
1433
|
)
|
|
1425
1434
|
ind_docs = write_individual_symbol_docs(
|
|
1426
|
-
target_dir,
|
|
1435
|
+
target_dir,
|
|
1436
|
+
rel_path,
|
|
1437
|
+
symbols,
|
|
1438
|
+
language=norm_lang,
|
|
1439
|
+
labels=doc_labels,
|
|
1427
1440
|
)
|
|
1428
1441
|
total_individual_docs += len(ind_docs)
|
|
1429
1442
|
db.update_file_hash(rel_path.as_posix(), current_hash)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pystdoc
|
|
3
|
-
Version: 0.8.
|
|
3
|
+
Version: 0.8.3
|
|
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
|
|
@@ -10,6 +10,7 @@ src/pystdoc/compilation_db.py
|
|
|
10
10
|
src/pystdoc/config.py
|
|
11
11
|
src/pystdoc/db.py
|
|
12
12
|
src/pystdoc/design_engine.py
|
|
13
|
+
src/pystdoc/doc_labels.py
|
|
13
14
|
src/pystdoc/doc_writer.py
|
|
14
15
|
src/pystdoc/engine.py
|
|
15
16
|
src/pystdoc/hasher.py
|
|
@@ -64,6 +65,7 @@ tests/test_pep8.py
|
|
|
64
65
|
tests/test_perf.py
|
|
65
66
|
tests/test_progress.py
|
|
66
67
|
tests/test_query.py
|
|
68
|
+
tests/test_real_litert_server.py
|
|
67
69
|
tests/test_reduce_cache.py
|
|
68
70
|
tests/test_reportgen.py
|
|
69
71
|
tests/test_ui_detector.py
|
|
@@ -193,6 +193,97 @@ class TestConfig(unittest.TestCase):
|
|
|
193
193
|
cfg = load_config(tmp_path)
|
|
194
194
|
self.assertEqual(cfg["language"], "Japanese")
|
|
195
195
|
|
|
196
|
+
def test_doc_labels_initialization_and_customization(self):
|
|
197
|
+
from unittest.mock import MagicMock
|
|
198
|
+
from pystdoc.doc_labels import (
|
|
199
|
+
get_or_init_document_labels,
|
|
200
|
+
DEFAULT_ENGLISH_LABELS,
|
|
201
|
+
)
|
|
202
|
+
|
|
203
|
+
with tempfile.TemporaryDirectory() as tmpdir:
|
|
204
|
+
tmp_path = Path(tmpdir)
|
|
205
|
+
# 1. English initialization
|
|
206
|
+
en_labels = get_or_init_document_labels(tmp_path, "English")
|
|
207
|
+
self.assertEqual(
|
|
208
|
+
en_labels["basic_info_title"],
|
|
209
|
+
DEFAULT_ENGLISH_LABELS["basic_info_title"],
|
|
210
|
+
)
|
|
211
|
+
labels_file = tmp_path / ".pystdoc" / "document_labels.json"
|
|
212
|
+
self.assertTrue(labels_file.exists())
|
|
213
|
+
|
|
214
|
+
# 2. Japanese initialization with LLM client
|
|
215
|
+
mock_llm = MagicMock()
|
|
216
|
+
mock_llm.chat_completion.return_value = json.dumps({
|
|
217
|
+
"language": "Japanese",
|
|
218
|
+
"doc_title_template": "{kind}仕様書: `{name}`",
|
|
219
|
+
"basic_info_title": "## 1. 基本情報",
|
|
220
|
+
"label_symbol_kind": "シンボル種別",
|
|
221
|
+
"kind_function": "関数",
|
|
222
|
+
})
|
|
223
|
+
ja_labels = get_or_init_document_labels(
|
|
224
|
+
tmp_path, "Japanese", llm_client=mock_llm
|
|
225
|
+
)
|
|
226
|
+
self.assertEqual(ja_labels["basic_info_title"], "## 1. 基本情報")
|
|
227
|
+
self.assertEqual(ja_labels["label_symbol_kind"], "シンボル種別")
|
|
228
|
+
self.assertEqual(ja_labels["kind_function"], "関数")
|
|
229
|
+
self.assertEqual(
|
|
230
|
+
ja_labels["doc_title_template"], "{kind}仕様書: `{name}`"
|
|
231
|
+
)
|
|
232
|
+
|
|
233
|
+
# 3. Customization in JSON file is preserved
|
|
234
|
+
loaded = json.loads(labels_file.read_text(encoding="utf-8"))
|
|
235
|
+
loaded["basic_info_title"] = "## 1. カスタム基本情報"
|
|
236
|
+
labels_file.write_text(
|
|
237
|
+
json.dumps(loaded, ensure_ascii=False), encoding="utf-8"
|
|
238
|
+
)
|
|
239
|
+
|
|
240
|
+
custom_labels = get_or_init_document_labels(tmp_path, "Japanese")
|
|
241
|
+
self.assertEqual(
|
|
242
|
+
custom_labels["basic_info_title"], "## 1. カスタム基本情報"
|
|
243
|
+
)
|
|
244
|
+
|
|
245
|
+
def test_doc_labels_llm_generation_for_other_languages(self):
|
|
246
|
+
from pystdoc.doc_labels import get_or_init_document_labels
|
|
247
|
+
from unittest.mock import MagicMock
|
|
248
|
+
|
|
249
|
+
mock_llm = MagicMock()
|
|
250
|
+
mock_llm.chat_completion.return_value = json.dumps({
|
|
251
|
+
"language": "German",
|
|
252
|
+
"basic_info_title": "## 1. Grundlegende Informationen",
|
|
253
|
+
"label_name": "Name",
|
|
254
|
+
"label_symbol_kind": "Symbolart",
|
|
255
|
+
"label_location": "Speicherort",
|
|
256
|
+
"source_code_snippet_title": "## Quellcode-Ausschnitt",
|
|
257
|
+
})
|
|
258
|
+
|
|
259
|
+
with tempfile.TemporaryDirectory() as tmpdir:
|
|
260
|
+
tmp_path = Path(tmpdir)
|
|
261
|
+
de_labels = get_or_init_document_labels(
|
|
262
|
+
tmp_path, "German", llm_client=mock_llm
|
|
263
|
+
)
|
|
264
|
+
self.assertEqual(de_labels["language"], "German")
|
|
265
|
+
self.assertEqual(
|
|
266
|
+
de_labels["basic_info_title"],
|
|
267
|
+
"## 1. Grundlegende Informationen",
|
|
268
|
+
)
|
|
269
|
+
self.assertEqual(de_labels["label_symbol_kind"], "Symbolart")
|
|
270
|
+
labels_file = tmp_path / ".pystdoc" / "document_labels.json"
|
|
271
|
+
self.assertTrue(labels_file.exists())
|
|
272
|
+
self.assertIn(
|
|
273
|
+
"Grundlegende", labels_file.read_text(encoding="utf-8")
|
|
274
|
+
)
|
|
275
|
+
|
|
276
|
+
# Next call uses cached file without calling LLM again
|
|
277
|
+
mock_llm.chat_completion.reset_mock()
|
|
278
|
+
de_labels_cached = get_or_init_document_labels(
|
|
279
|
+
tmp_path, "German", llm_client=mock_llm
|
|
280
|
+
)
|
|
281
|
+
self.assertEqual(mock_llm.chat_completion.call_count, 0)
|
|
282
|
+
self.assertEqual(
|
|
283
|
+
de_labels_cached["basic_info_title"],
|
|
284
|
+
"## 1. Grundlegende Informationen",
|
|
285
|
+
)
|
|
286
|
+
|
|
196
287
|
|
|
197
288
|
if __name__ == "__main__":
|
|
198
289
|
unittest.main()
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env python3
|
|
2
2
|
"""Unit tests for docgen."""
|
|
3
3
|
|
|
4
|
+
import json
|
|
4
5
|
import shutil
|
|
5
6
|
import tempfile
|
|
6
7
|
import unittest
|
|
@@ -154,7 +155,18 @@ class TestDocgen(unittest.TestCase):
|
|
|
154
155
|
self.assertIn("## 1. Basic Information", doc_en)
|
|
155
156
|
self.assertIn("Executes `add` operations.", doc_en)
|
|
156
157
|
|
|
157
|
-
# Japanese option
|
|
158
|
+
# Japanese option with pre-existing / customized document_labels.json
|
|
159
|
+
labels_path = self.test_dir / ".pystdoc" / "document_labels.json"
|
|
160
|
+
labels_path.parent.mkdir(parents=True, exist_ok=True)
|
|
161
|
+
labels_path.write_text(
|
|
162
|
+
json.dumps({
|
|
163
|
+
"language": "Japanese",
|
|
164
|
+
"doc_title_template": "{kind}仕様書: `{name}`",
|
|
165
|
+
"basic_info_title": "## 1. 基本情報",
|
|
166
|
+
"kind_function": "関数",
|
|
167
|
+
}, ensure_ascii=False),
|
|
168
|
+
encoding="utf-8",
|
|
169
|
+
)
|
|
158
170
|
res_ja = run_docgen(
|
|
159
171
|
target_dir=self.test_dir,
|
|
160
172
|
use_llm=False,
|
|
@@ -166,7 +178,8 @@ class TestDocgen(unittest.TestCase):
|
|
|
166
178
|
doc_ja = (
|
|
167
179
|
self.test_dir / ".pystdoc" / "documents" / "src" / "sample.c.md"
|
|
168
180
|
).read_text(encoding="utf-8")
|
|
169
|
-
self.assertIn("## 1.
|
|
181
|
+
self.assertIn("## 1. 基本情報", doc_ja)
|
|
182
|
+
self.assertIn("関数仕様書: `add`", doc_ja)
|
|
170
183
|
self.assertIn("`add` の処理を実行する。", doc_ja)
|
|
171
184
|
|
|
172
185
|
def test_llm_client_host_and_token(self):
|
|
@@ -224,8 +224,8 @@ class TestLiveServer100(unittest.TestCase):
|
|
|
224
224
|
self.assertTrue(main_doc_path.exists())
|
|
225
225
|
doc_content = main_doc_path.read_text(encoding="utf-8")
|
|
226
226
|
|
|
227
|
-
# 1. Must contain Basic Information section
|
|
228
|
-
self.assertIn("## 1.
|
|
227
|
+
# 1. Must contain Basic Information section (Japanese localized)
|
|
228
|
+
self.assertIn("## 1. 基本情報", doc_content)
|
|
229
229
|
# 2. Must contain the role generated by LLM (from MockLLMHandler)
|
|
230
230
|
self.assertIn("Main computation unit", doc_content)
|
|
231
231
|
# 3. Must NOT contain the old superficial fallback template
|
|
@@ -0,0 +1,240 @@
|
|
|
1
|
+
"""Live integration tests using real LiteRT-LM Gemma 4 server on LAN."""
|
|
2
|
+
|
|
3
|
+
import shutil
|
|
4
|
+
import tempfile
|
|
5
|
+
import unittest
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from pystdoc.db import DocgenDB
|
|
9
|
+
from pystdoc.design_engine import run_design_generation
|
|
10
|
+
from pystdoc.engine import run_docgen
|
|
11
|
+
from pystdoc.llm_client import LLMClient
|
|
12
|
+
from pystdoc.report_engine import generate_readme_doc
|
|
13
|
+
|
|
14
|
+
REAL_SERVER_HOST = "http://192.168.11.6:11434"
|
|
15
|
+
REAL_SERVER_MODEL = "gemma4-26b-a4b"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def is_real_server_available() -> bool:
|
|
19
|
+
"""Check if the real LiteRT-LM server is reachable."""
|
|
20
|
+
try:
|
|
21
|
+
client = LLMClient(
|
|
22
|
+
host=REAL_SERVER_HOST,
|
|
23
|
+
model=REAL_SERVER_MODEL,
|
|
24
|
+
)
|
|
25
|
+
return client.check_availability()
|
|
26
|
+
except Exception:
|
|
27
|
+
return False
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@unittest.skipUnless(
|
|
31
|
+
is_real_server_available(),
|
|
32
|
+
f"Real LiteRT-LM server not reachable at {REAL_SERVER_HOST}",
|
|
33
|
+
)
|
|
34
|
+
class TestRealLiteRTServer(unittest.TestCase):
|
|
35
|
+
def setUp(self):
|
|
36
|
+
self.test_dir = Path(tempfile.mkdtemp())
|
|
37
|
+
self.src_dir = self.test_dir / "src"
|
|
38
|
+
self.src_dir.mkdir(parents=True, exist_ok=True)
|
|
39
|
+
|
|
40
|
+
def tearDown(self):
|
|
41
|
+
shutil.rmtree(self.test_dir, ignore_errors=True)
|
|
42
|
+
|
|
43
|
+
def test_real_server_explain_symbol_and_labels(self):
|
|
44
|
+
"""Test symbol explanation on Gemma 4 and document_labels.json."""
|
|
45
|
+
py_file = self.src_dir / "math_service.py"
|
|
46
|
+
py_file.write_text(
|
|
47
|
+
"def multiply(a: int, b: int) -> int:\n"
|
|
48
|
+
" \"\"\"Multiply two integers.\"\"\"\n"
|
|
49
|
+
" return a * b\n\n"
|
|
50
|
+
"def compute_total(x: int) -> int:\n"
|
|
51
|
+
" return multiply(x, 10)\n",
|
|
52
|
+
encoding="utf-8",
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
ret = run_docgen(
|
|
56
|
+
target_dir=self.test_dir,
|
|
57
|
+
use_llm=True,
|
|
58
|
+
host=REAL_SERVER_HOST,
|
|
59
|
+
model=REAL_SERVER_MODEL,
|
|
60
|
+
language="Japanese",
|
|
61
|
+
force=True,
|
|
62
|
+
)
|
|
63
|
+
self.assertEqual(ret, 0)
|
|
64
|
+
|
|
65
|
+
# 1. Verify .pystdoc/document_labels.json was created
|
|
66
|
+
# with Japanese software terms
|
|
67
|
+
labels_file = self.test_dir / ".pystdoc" / "document_labels.json"
|
|
68
|
+
self.assertTrue(labels_file.exists())
|
|
69
|
+
labels_text = labels_file.read_text(encoding="utf-8")
|
|
70
|
+
self.assertIn('"language": "Japanese"', labels_text)
|
|
71
|
+
self.assertIn('"basic_info_title": "## 1. 基本情報"', labels_text)
|
|
72
|
+
self.assertIn('"label_symbol_kind": "シンボル種別"', labels_text)
|
|
73
|
+
|
|
74
|
+
# 2. Verify symbol doc contains Japanese headings and 関数仕様書
|
|
75
|
+
mul_doc = (
|
|
76
|
+
self.test_dir
|
|
77
|
+
/ ".pystdoc"
|
|
78
|
+
/ "documents"
|
|
79
|
+
/ "src"
|
|
80
|
+
/ "math_service.py.fn.multiply.md"
|
|
81
|
+
)
|
|
82
|
+
self.assertTrue(mul_doc.exists())
|
|
83
|
+
doc_text = mul_doc.read_text(encoding="utf-8")
|
|
84
|
+
self.assertIn("関数仕様書: `multiply`", doc_text)
|
|
85
|
+
self.assertNotIn("Function 仕様書", doc_text)
|
|
86
|
+
self.assertIn("## 1. 基本情報", doc_text)
|
|
87
|
+
self.assertIn("- **シンボル種別**:", doc_text)
|
|
88
|
+
self.assertIn("## 3.", doc_text)
|
|
89
|
+
self.assertIn("return a * b", doc_text)
|
|
90
|
+
|
|
91
|
+
def test_real_server_sync_and_early_stopping_code_flush(self):
|
|
92
|
+
"""Test bottom-up sync with early stopping updates code snippets."""
|
|
93
|
+
c_file = self.src_dir / "calculator.c"
|
|
94
|
+
c_file.write_text(
|
|
95
|
+
"int add(int a, int b) {\n"
|
|
96
|
+
" return a + b;\n"
|
|
97
|
+
"}\n"
|
|
98
|
+
"int calculate(int x) {\n"
|
|
99
|
+
" return add(x, 5);\n"
|
|
100
|
+
"}\n",
|
|
101
|
+
encoding="utf-8",
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
ret1 = run_docgen(
|
|
105
|
+
target_dir=self.test_dir,
|
|
106
|
+
use_llm=True,
|
|
107
|
+
host=REAL_SERVER_HOST,
|
|
108
|
+
model=REAL_SERVER_MODEL,
|
|
109
|
+
language="Japanese",
|
|
110
|
+
)
|
|
111
|
+
self.assertEqual(ret1, 0)
|
|
112
|
+
|
|
113
|
+
add_doc = (
|
|
114
|
+
self.test_dir
|
|
115
|
+
/ ".pystdoc"
|
|
116
|
+
/ "documents"
|
|
117
|
+
/ "src"
|
|
118
|
+
/ "calculator.c.fn.add.md"
|
|
119
|
+
)
|
|
120
|
+
self.assertTrue(add_doc.exists())
|
|
121
|
+
self.assertIn("return a + b;", add_doc.read_text(encoding="utf-8"))
|
|
122
|
+
|
|
123
|
+
# Modify add() internal code without changing external signature
|
|
124
|
+
import time
|
|
125
|
+
time.sleep(0.05)
|
|
126
|
+
c_file.write_text(
|
|
127
|
+
"int add(int a, int b) {\n"
|
|
128
|
+
" int sum = a + b;\n"
|
|
129
|
+
" return sum;\n"
|
|
130
|
+
"}\n"
|
|
131
|
+
"int calculate(int x) {\n"
|
|
132
|
+
" return add(x, 5);\n"
|
|
133
|
+
"}\n",
|
|
134
|
+
encoding="utf-8",
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
ret2 = run_docgen(
|
|
138
|
+
target_dir=self.test_dir,
|
|
139
|
+
use_llm=True,
|
|
140
|
+
host=REAL_SERVER_HOST,
|
|
141
|
+
model=REAL_SERVER_MODEL,
|
|
142
|
+
language="Japanese",
|
|
143
|
+
)
|
|
144
|
+
self.assertEqual(ret2, 0)
|
|
145
|
+
|
|
146
|
+
# Code snippet must be updated with newest implementation
|
|
147
|
+
updated_add = add_doc.read_text(encoding="utf-8")
|
|
148
|
+
self.assertIn("int sum = a + b;", updated_add)
|
|
149
|
+
|
|
150
|
+
def test_real_server_full_pipeline_sync(self):
|
|
151
|
+
"""Test full pipeline: docgen -> designgen -> reportgen on Gemma 4."""
|
|
152
|
+
py_file = self.src_dir / "app_entry.py"
|
|
153
|
+
py_file.write_text(
|
|
154
|
+
"def main():\n"
|
|
155
|
+
" print('App running')\n"
|
|
156
|
+
" return 0\n",
|
|
157
|
+
encoding="utf-8",
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
# Step 1-2: docgen
|
|
161
|
+
ret_docgen = run_docgen(
|
|
162
|
+
target_dir=self.test_dir,
|
|
163
|
+
use_llm=True,
|
|
164
|
+
host=REAL_SERVER_HOST,
|
|
165
|
+
model=REAL_SERVER_MODEL,
|
|
166
|
+
language="Japanese",
|
|
167
|
+
)
|
|
168
|
+
self.assertEqual(ret_docgen, 0)
|
|
169
|
+
|
|
170
|
+
# Step 3: designgen
|
|
171
|
+
ret_design = run_design_generation(
|
|
172
|
+
target_dir=self.test_dir,
|
|
173
|
+
use_llm=True,
|
|
174
|
+
host=REAL_SERVER_HOST,
|
|
175
|
+
model=REAL_SERVER_MODEL,
|
|
176
|
+
language="Japanese",
|
|
177
|
+
)
|
|
178
|
+
self.assertEqual(ret_design, 0)
|
|
179
|
+
self.assertTrue(
|
|
180
|
+
(self.test_dir / ".pystdoc" / "design" / "overview.md").exists()
|
|
181
|
+
)
|
|
182
|
+
|
|
183
|
+
# Step 4: reportgen (README)
|
|
184
|
+
client = LLMClient(host=REAL_SERVER_HOST, model=REAL_SERVER_MODEL)
|
|
185
|
+
db_path = self.test_dir / ".pystdoc" / "index.db"
|
|
186
|
+
db = DocgenDB(db_path)
|
|
187
|
+
ret_readme = generate_readme_doc(
|
|
188
|
+
target_dir=self.test_dir,
|
|
189
|
+
llm_client=client,
|
|
190
|
+
language="Japanese",
|
|
191
|
+
db=db,
|
|
192
|
+
)
|
|
193
|
+
db.close()
|
|
194
|
+
self.assertTrue(bool(ret_readme))
|
|
195
|
+
readme_path = self.test_dir / ".pystdoc" / "README.md"
|
|
196
|
+
self.assertTrue(readme_path.exists())
|
|
197
|
+
|
|
198
|
+
def test_real_server_foreign_language_labels_generation(self):
|
|
199
|
+
"""Test LLM generation of document_labels.json for foreign language."""
|
|
200
|
+
py_file = self.src_dir / "greeter.py"
|
|
201
|
+
py_file.write_text(
|
|
202
|
+
"def greet(name: str) -> str:\n"
|
|
203
|
+
" \"\"\"Return greeting message.\"\"\"\n"
|
|
204
|
+
" return f'Hello, {name}'\n",
|
|
205
|
+
encoding="utf-8",
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
ret = run_docgen(
|
|
209
|
+
target_dir=self.test_dir,
|
|
210
|
+
use_llm=True,
|
|
211
|
+
host=REAL_SERVER_HOST,
|
|
212
|
+
model=REAL_SERVER_MODEL,
|
|
213
|
+
language="German",
|
|
214
|
+
force=True,
|
|
215
|
+
)
|
|
216
|
+
self.assertEqual(ret, 0)
|
|
217
|
+
|
|
218
|
+
# 1. Verify .pystdoc/document_labels.json was generated by LLM
|
|
219
|
+
labels_file = self.test_dir / ".pystdoc" / "document_labels.json"
|
|
220
|
+
self.assertTrue(labels_file.exists())
|
|
221
|
+
labels_text = labels_file.read_text(encoding="utf-8")
|
|
222
|
+
self.assertIn('"language": "German"', labels_text)
|
|
223
|
+
|
|
224
|
+
# 2. Verify symbol doc exists and uses generated labels
|
|
225
|
+
greet_doc = (
|
|
226
|
+
self.test_dir
|
|
227
|
+
/ ".pystdoc"
|
|
228
|
+
/ "documents"
|
|
229
|
+
/ "src"
|
|
230
|
+
/ "greeter.py.fn.greet.md"
|
|
231
|
+
)
|
|
232
|
+
self.assertTrue(greet_doc.exists())
|
|
233
|
+
doc_text = greet_doc.read_text(encoding="utf-8")
|
|
234
|
+
# German document should contain generated heading (not empty)
|
|
235
|
+
self.assertIn("##", doc_text)
|
|
236
|
+
self.assertIn("greet", doc_text)
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
if __name__ == "__main__":
|
|
240
|
+
unittest.main()
|
|
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
|
|
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
|
|
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
|