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.
Files changed (74) hide show
  1. {pystdoc-0.8.2/src/pystdoc.egg-info → pystdoc-0.8.3}/PKG-INFO +1 -1
  2. {pystdoc-0.8.2 → pystdoc-0.8.3}/pyproject.toml +1 -1
  3. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/__init__.py +1 -1
  4. pystdoc-0.8.3/src/pystdoc/doc_labels.py +171 -0
  5. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/doc_writer.py +144 -47
  6. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/engine.py +14 -1
  7. {pystdoc-0.8.2 → pystdoc-0.8.3/src/pystdoc.egg-info}/PKG-INFO +1 -1
  8. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/SOURCES.txt +2 -0
  9. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_config.py +91 -0
  10. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_docgen.py +15 -2
  11. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_live_server_100.py +2 -2
  12. pystdoc-0.8.3/tests/test_real_litert_server.py +240 -0
  13. {pystdoc-0.8.2 → pystdoc-0.8.3}/LICENSE +0 -0
  14. {pystdoc-0.8.2 → pystdoc-0.8.3}/README.md +0 -0
  15. {pystdoc-0.8.2 → pystdoc-0.8.3}/setup.cfg +0 -0
  16. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/__main__.py +0 -0
  17. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/__init__.py +0 -0
  18. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/base.py +0 -0
  19. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/clang_adapter.py +0 -0
  20. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/generic_adapter.py +0 -0
  21. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/java_adapter.py +0 -0
  22. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/kotlin_adapter.py +0 -0
  23. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/adapters/python_adapter.py +0 -0
  24. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/cache.py +0 -0
  25. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/call_graph.py +0 -0
  26. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/cli.py +0 -0
  27. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/compilation_db.py +0 -0
  28. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/config.py +0 -0
  29. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/db.py +0 -0
  30. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/design_engine.py +0 -0
  31. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/hasher.py +0 -0
  32. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/interrupt.py +0 -0
  33. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/llm_client.py +0 -0
  34. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/mcp_server.py +0 -0
  35. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_clang.py +0 -0
  36. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_generic.py +0 -0
  37. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_java.py +0 -0
  38. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_kotlin.py +0 -0
  39. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/parser_python.py +0 -0
  40. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/perf.py +0 -0
  41. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/progress.py +0 -0
  42. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/query.py +0 -0
  43. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/report_engine.py +0 -0
  44. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/scanner.py +0 -0
  45. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/similarity.py +0 -0
  46. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/symbols.py +0 -0
  47. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/ui_detector.py +0 -0
  48. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc/watcher.py +0 -0
  49. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/dependency_links.txt +0 -0
  50. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/entry_points.txt +0 -0
  51. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/requires.txt +0 -0
  52. {pystdoc-0.8.2 → pystdoc-0.8.3}/src/pystdoc.egg-info/top_level.txt +0 -0
  53. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_adapters.py +0 -0
  54. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_cli.py +0 -0
  55. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_coverage_boost.py +0 -0
  56. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_design_engine_full.py +0 -0
  57. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_designgen.py +0 -0
  58. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_engine.py +0 -0
  59. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_engine_full.py +0 -0
  60. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_final_100.py +0 -0
  61. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_interrupt.py +0 -0
  62. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_llm_client.py +0 -0
  63. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_mcp_server.py +0 -0
  64. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_parser_generic.py +0 -0
  65. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_parser_java.py +0 -0
  66. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_parser_kotlin.py +0 -0
  67. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_pep8.py +0 -0
  68. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_perf.py +0 -0
  69. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_progress.py +0 -0
  70. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_query.py +0 -0
  71. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_reduce_cache.py +0 -0
  72. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_reportgen.py +0 -0
  73. {pystdoc-0.8.2 → pystdoc-0.8.3}/tests/test_ui_detector.py +0 -0
  74. {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.2
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.2"
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 = [
@@ -1,3 +1,3 @@
1
1
  """pystdoc: Python Structural & Topological Documentation Engine (pystdoc)."""
2
2
 
3
- __version__ = "0.8.2"
3
+ __version__ = "0.8.3"
@@ -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
- kind_display = sym.kind
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"{sym.kind} (FQDN: `{sym.fqdn}`)"
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
- if is_ja:
180
- prose_sentences.append(
181
- f"上位モジュールからは、{callers_str} などの目的で利用・参照されます。"
182
- )
183
- else:
184
- prose_sentences.append(
185
- f"In the system architecture, it is referenced by "
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
- if is_ja:
190
- prose_sentences.append(
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
- else:
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
- if is_ja:
210
- prose_sentences.append(f"実装面では、{sym.overview}")
211
- else:
212
- prose_sentences.append(
213
- f"Implementation overview: {sym.overview}"
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} {sym.kind.capitalize()} Documentation: `{sym.name}`",
263
+ f"{h_prefix} {doc_title}",
220
264
  "",
221
265
  prose_paragraph,
222
266
  "",
223
- "## 1. Basic Information",
224
- f"- **Name**: `{sym.name}`",
225
- f"- **FQDN**: `{sym.fqdn or sym.name}`",
226
- f"- **Symbol Kind**: `{kind_display}`",
227
- f"- **Location**: Line {sym.line_start} to Line {sym.line_end}",
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
- lines.append(f"- **Signature / Type**: `{sym.signature}`")
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(["", "## 2. Parameters"])
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(["", "## 2. Parameters", "- None"])
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
- lines.extend(["", "## 3. Input / Return Specifications"])
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
- lines.append(f"- Input Constraints: {sym.inputs_note}")
244
- lines.append(f"- Return Type: `{sym.return_type or 'void / None'}`")
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
- lines.append(f"- Return Value & Side Effects: {sym.outputs_note}")
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
- lines.extend(["", "## 4. Called Functions"])
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
- lines.extend(["", "## 4. Referencing Functions"])
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
- "## Source Code Snippet",
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, file_path, level=level + 1, language=norm_lang
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"# File Documentation: `{rel_path.as_posix()}`",
448
+ f"# {title_fmt.format(path=rel_path.as_posix())}",
364
449
  "",
365
- f"- **File SHA-256**: `{file_hash}`",
366
- f"- **Detected Symbols**: {len(symbols)}",
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
- f"- `{sym.name}` ({sym.kind}) [Lines: {line_range}]"
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(sym, full_path, level=2, language=norm_lang)
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, rel_path, symbols, language=norm_lang
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.2
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. Basic Information", doc_ja)
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. Basic Information", doc_content)
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