pytexmk 1.2.4__tar.gz → 1.2.7__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 (133) hide show
  1. pytexmk-1.2.7/PKG-INFO +458 -0
  2. pytexmk-1.2.7/README.md +423 -0
  3. pytexmk-1.2.7/pyproject.toml +141 -0
  4. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/__init__.py +11 -4
  5. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/__main__.py +3 -1
  6. pytexmk-1.2.7/src/pytexmk/aux_repair.py +182 -0
  7. pytexmk-1.2.7/src/pytexmk/build_state.py +218 -0
  8. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/cli/__main__.py +13 -1
  9. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/cli/check_version.py +6 -6
  10. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/cli/cli_args.py +6 -0
  11. pytexmk-1.2.7/src/pytexmk/cli/cli_compile.py +296 -0
  12. pytexmk-1.2.7/src/pytexmk/cli/cli_context.py +207 -0
  13. pytexmk-1.2.7/src/pytexmk/cli/cli_early.py +112 -0
  14. pytexmk-1.2.7/src/pytexmk/cli/cli_latexdiff.py +180 -0
  15. pytexmk-1.2.7/src/pytexmk/cli/cli_state.py +87 -0
  16. pytexmk-1.2.7/src/pytexmk/cli/cli_workflow.py +45 -0
  17. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/compile.py +17 -29
  18. pytexmk-1.2.7/src/pytexmk/compile_engine.py +463 -0
  19. pytexmk-1.2.7/src/pytexmk/compile_report.py +125 -0
  20. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/config.py +1 -1
  21. pytexmk-1.2.7/src/pytexmk/context.py +174 -0
  22. pytexmk-1.2.7/src/pytexmk/data/README.html +575 -0
  23. pytexmk-1.2.7/src/pytexmk/detection.py +1038 -0
  24. pytexmk-1.2.7/src/pytexmk/file_ops.py +126 -0
  25. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/language.py +83 -7
  26. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/latexdiff.py +27 -61
  27. pytexmk-1.2.7/src/pytexmk/lifecycle.py +36 -0
  28. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/__main__.mo +0 -0
  29. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/aux_repair.mo +0 -0
  30. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/context.mo → pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/build_state.mo +0 -0
  31. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/check_version.mo +0 -0
  32. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/cli_args.mo +0 -0
  33. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/cli_workflow.mo +0 -0
  34. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/compile.mo +0 -0
  35. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/compile_engine.mo +0 -0
  36. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/compile_report.mo +0 -0
  37. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/config.mo +0 -0
  38. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/context.mo +0 -0
  39. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/detection.mo +0 -0
  40. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/file_ops.mo +0 -0
  41. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/latexdiff.mo +0 -0
  42. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/lifecycle.mo +0 -0
  43. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/logger_config.mo +0 -0
  44. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/paths.mo +0 -0
  45. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/pdf_tools.mo +0 -0
  46. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/subprocess_runner.mo +0 -0
  47. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/en/LC_MESSAGES/subproject.mo +0 -0
  48. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/tex_project.mo +0 -0
  49. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/timing.mo +0 -0
  50. pytexmk-1.2.7/src/pytexmk/locale/en/LC_MESSAGES/ui_messages.mo +0 -0
  51. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/__main__.pot +2 -2
  52. pytexmk-1.2.4/src/pytexmk/locale/templates/subprocess_runner.pot → pytexmk-1.2.7/src/pytexmk/locale/templates/aux_repair.pot +5 -5
  53. pytexmk-1.2.4/src/pytexmk/locale/templates/context.pot → pytexmk-1.2.7/src/pytexmk/locale/templates/build_state.pot +2 -3
  54. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/check_version.pot +5 -2
  55. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/cli_args.pot +5 -2
  56. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/cli_workflow.pot +104 -76
  57. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/compile.pot +2 -2
  58. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/compile_engine.pot +7 -6
  59. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/compile_report.pot +21 -6
  60. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/config.pot +2 -2
  61. pytexmk-1.2.4/src/pytexmk/locale/templates/detection.pot → pytexmk-1.2.7/src/pytexmk/locale/templates/context.pot +5 -4
  62. pytexmk-1.2.7/src/pytexmk/locale/templates/detection.pot +39 -0
  63. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/file_ops.pot +2 -2
  64. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/latexdiff.pot +4 -4
  65. pytexmk-1.2.7/src/pytexmk/locale/templates/lifecycle.pot +34 -0
  66. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/logger_config.pot +2 -2
  67. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/paths.pot +2 -2
  68. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/pdf_tools.pot +2 -2
  69. pytexmk-1.2.7/src/pytexmk/locale/templates/subprocess_runner.pot +45 -0
  70. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/subproject.pot +2 -2
  71. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/tex_project.pot +15 -5
  72. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/timing.pot +2 -5
  73. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/ui_messages.pot +2 -5
  74. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/logger_config.py +2 -1
  75. pytexmk-1.2.7/src/pytexmk/subprocess_runner.py +225 -0
  76. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/subproject_scanner.py +1 -2
  77. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/tex_project.py +75 -109
  78. pytexmk-1.2.7/src/pytexmk/timing.py +165 -0
  79. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/ui_messages.py +25 -31
  80. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/version.py +4 -5
  81. pytexmk-1.2.7/src/pytexmk.egg-info/PKG-INFO +458 -0
  82. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk.egg-info/SOURCES.txt +16 -0
  83. pytexmk-1.2.7/src/pytexmk.egg-info/requires.txt +13 -0
  84. pytexmk-1.2.7/tests/test_build_state.py +265 -0
  85. pytexmk-1.2.7/tests/test_compile_convergence.py +193 -0
  86. {pytexmk-1.2.4 → pytexmk-1.2.7}/tests/test_config_merge.py +2 -3
  87. {pytexmk-1.2.4 → pytexmk-1.2.7}/tests/test_context.py +5 -3
  88. pytexmk-1.2.7/tests/test_packaging_metadata.py +67 -0
  89. pytexmk-1.2.7/tests/test_signal_classification.py +163 -0
  90. pytexmk-1.2.7/tests/test_subproject_resolution.py +152 -0
  91. {pytexmk-1.2.4 → pytexmk-1.2.7}/tests/test_subproject_scanner.py +1 -2
  92. pytexmk-1.2.7/tests/test_tex_project.py +71 -0
  93. pytexmk-1.2.4/PKG-INFO +0 -391
  94. pytexmk-1.2.4/README.md +0 -358
  95. pytexmk-1.2.4/pyproject.toml +0 -100
  96. pytexmk-1.2.4/src/pytexmk/cli/cli_workflow.py +0 -445
  97. pytexmk-1.2.4/src/pytexmk/compile_engine.py +0 -256
  98. pytexmk-1.2.4/src/pytexmk/compile_report.py +0 -101
  99. pytexmk-1.2.4/src/pytexmk/context.py +0 -94
  100. pytexmk-1.2.4/src/pytexmk/data/README.html +0 -504
  101. pytexmk-1.2.4/src/pytexmk/detection.py +0 -531
  102. pytexmk-1.2.4/src/pytexmk/file_ops.py +0 -149
  103. pytexmk-1.2.4/src/pytexmk/lifecycle.py +0 -22
  104. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/check_version.mo +0 -0
  105. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/cli_workflow.mo +0 -0
  106. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/compile_engine.mo +0 -0
  107. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/compile_report.mo +0 -0
  108. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/detection.mo +0 -0
  109. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/lifecycle.mo +0 -0
  110. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/subprocess_runner.mo +0 -0
  111. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/tex_project.mo +0 -0
  112. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/timing.mo +0 -0
  113. pytexmk-1.2.4/src/pytexmk/locale/en/LC_MESSAGES/ui_messages.mo +0 -0
  114. pytexmk-1.2.4/src/pytexmk/locale/templates/lifecycle.pot +0 -22
  115. pytexmk-1.2.4/src/pytexmk/subprocess_runner.py +0 -126
  116. pytexmk-1.2.4/src/pytexmk/timing.py +0 -155
  117. pytexmk-1.2.4/src/pytexmk.egg-info/PKG-INFO +0 -391
  118. pytexmk-1.2.4/src/pytexmk.egg-info/requires.txt +0 -13
  119. pytexmk-1.2.4/tests/test_tex_project.py +0 -14
  120. {pytexmk-1.2.4 → pytexmk-1.2.7}/LICENSE +0 -0
  121. {pytexmk-1.2.4 → pytexmk-1.2.7}/setup.cfg +0 -0
  122. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/cli/__init__.py +0 -0
  123. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/data/__init__.py +0 -0
  124. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/data/default_project_config.toml +0 -0
  125. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/data/default_user_config.toml +0 -0
  126. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/__init__.py +0 -0
  127. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/locale/templates/__init__.py +0 -0
  128. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/paths.py +0 -0
  129. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/pdf_tools.py +0 -0
  130. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk/ui_theme.py +0 -0
  131. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk.egg-info/dependency_links.txt +0 -0
  132. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk.egg-info/entry_points.txt +0 -0
  133. {pytexmk-1.2.4 → pytexmk-1.2.7}/src/pytexmk.egg-info/top_level.txt +0 -0
pytexmk-1.2.7/PKG-INFO ADDED
@@ -0,0 +1,458 @@
1
+ Metadata-Version: 2.4
2
+ Name: pytexmk
3
+ Version: 1.2.7
4
+ Summary: LaTeX 辅助编译命令行工具 LaTeX Auxiliary Compilation Command Line Tool
5
+ Author-email: 焱铭 <lxb-yanming@foxmail.com>
6
+ License-Expression: GPL-3.0-or-later
7
+ Project-URL: Homepage, https://github.com/YanMing-lxb/PyTeXMK
8
+ Project-URL: Bug Tracker, https://github.com/YanMing-lxb/PyTeXMK/issues
9
+ Keywords: LaTeX,build,latexmk
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Intended Audience :: Education
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.15
18
+ Classifier: Operating System :: OS Independent
19
+ Requires-Python: >=3.15
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: packaging>=26.3
23
+ Requires-Dist: platformdirs>=4.13.3
24
+ Requires-Dist: pypdf>=6.21.1
25
+ Requires-Dist: pytexlogs>=0.4.0
26
+ Requires-Dist: rich>=15.0.0
27
+ Requires-Dist: rich_argparse>=1.8.0
28
+ Requires-Dist: tomli-w>=1.2.0
29
+ Provides-Extra: dev
30
+ Requires-Dist: babel>=2.18.0; extra == "dev"
31
+ Requires-Dist: pillow>=13.0.0; extra == "dev"
32
+ Requires-Dist: pyinstaller>=6.22.3; extra == "dev"
33
+ Requires-Dist: pytest>=9.1.1; extra == "dev"
34
+ Dynamic: license-file
35
+
36
+ <div align="center">
37
+ <img src="https://github.com/YanMing-lxb/PyTeXMK/blob/main/imgs/pytexmk-logo.png?raw=true" alt="PyTeXMK Logo" width="128" height="128">
38
+ <h1>PyTeXMK</h1>
39
+ <p>LaTeX 辅助编译命令行工具</p>
40
+
41
+ <p>
42
+ <a href="https://pypi.python.org/pypi/pytexmk/">
43
+ <img src="https://img.shields.io/pypi/v/pytexmk.svg?color=blue" alt="PyPI version">
44
+ </a>
45
+ <a href="https://pypi.org/project/pytexmk/">
46
+ <img src="https://img.shields.io/pypi/dm/pytexmk.svg?label=PyPI%20downloads" alt="PyPI Downloads">
47
+ </a>
48
+ <a href="https://github.com/YanMing-lxb/PyTeXMK/releases/latest">
49
+ <img src="https://img.shields.io/github/release/YanMing-lxb/PyTeXMK.svg?color=blueviolet&label=release" alt="GitHub release">
50
+ </a>
51
+ <a href="https://github.com/YanMing-lxb/PyTeXMK/blob/main/LICENSE">
52
+ <img src="https://img.shields.io/badge/license-GPLv3-aff" alt="License">
53
+ </a>
54
+ <a href="#">
55
+ <img src="https://img.shields.io/badge/OS-Linux%20%7C%20Windows%20%7C%20macOS-pink.svg" alt="OS">
56
+ </a>
57
+ </p>
58
+
59
+ <p>
60
+ <a href="https://github.com/YanMing-lxb/PyTeXMK/issues">
61
+ <img src="https://img.shields.io/github/issues/YanMing-lxb/PyTeXMK" alt="Issues">
62
+ </a>
63
+ <a href="https://github.com/YanMing-lxb/PyTeXMK">
64
+ <img src="https://img.shields.io/github/last-commit/YanMing-lxb/PyTeXMK" alt="Last Commit">
65
+ </a>
66
+ <a href="https://github.com/YanMing-lxb/PyTeXMK">
67
+ <img src="https://img.shields.io/github/repo-size/YanMing-lxb/PyTeXMK" alt="Repo Size">
68
+ </a>
69
+ <a href="https://star-history.com/#YanMing-lxb/PyTeXMK&Date">
70
+ <img src="https://img.shields.io/github/stars/YanMing-lxb/PyTeXMK?style=social" alt="Stars">
71
+ </a>
72
+ </p>
73
+
74
+ <p>
75
+ <a href="README.md">简体中文</a>
76
+ ·
77
+ <a href="README.en.md">English</a>
78
+ </p>
79
+ </div>
80
+
81
+ ---
82
+
83
+ **PyTeXMK**(Python TeX Make)是一个用 Python 编写的 LaTeX 自动化编译工具,灵感来源于 `latexmk`。它能够根据辅助文件变化智能决定编译轮次,配合 Rich 彩色输出、参考文献/索引工具链自动调度,让 LaTeX 编译工作流一键完成。
84
+
85
+ ---
86
+
87
+ ## ✨ 功能特性
88
+
89
+ ### 核心编译
90
+
91
+ - 🚀 **多引擎支持**:XeLaTeX、PdfLaTeX、LuaLaTeX,通过命令行参数或魔法注释灵活切换
92
+ - 🔁 **智能多次编译检测**:自动比较 `.aux`/`.out` 文件内容并解析日志 Rerun 警告,确保交叉引用、hyperref 书签、总页数等收敛稳定
93
+ - 📋 **结构化编译检测报告**:每轮编译结束后输出 6 维检测状态(参考文献、索引、目录、交叉引用、书签文件、日志重编译),清晰展示各维度是否稳定及预期下一步
94
+
95
+ ### 参考文献与索引
96
+
97
+ - 📚 **参考文献**:自动调度 bibtex / biblatex(biber)/ thebibliography
98
+ - 📑 **索引与术语表**:glossaries(含 glossaries-extra + bib2gls + biber)、nomencl、makeidx,自动选择 xindy 或 makeindex 后端
99
+ - 🔮 **魔法注释**:通过 `% !TEX` 注释指定编译引擎、主文件、输出目录、辅助目录等
100
+
101
+ ### 辅助工具
102
+
103
+ - 🧹 **智能清理**:多种清理模式,支持按目录范围和文件后缀精确清理辅助文件
104
+ - 🔍 **日志解析**:编译失败后自动解析 LaTeX 日志,定位错误位置
105
+ - 📝 **LaTeXDiff**:两个 LaTeX 文件差异对比,生成带修订标记的 PDF
106
+ - 🖼 **PDF 修复与预览**:损坏 PDF 自动修复,编译后自动预览
107
+
108
+ ### 配置与扩展
109
+
110
+ - 🌍 **国际化**:支持多语言界面,默认中文
111
+ - ⚙️ **两级配置文件**:用户级 + 项目级 `.pytexmkrc`,所有参数均可自定义
112
+ - 🧩 **多子项目管理**:一个根目录下管理多个独立子项目,支持自动扫描和逐一编译
113
+ - 🪲 **版本检查**:自动检查更新,第一时间获取新版本
114
+
115
+ ---
116
+
117
+ ## 📸 预览
118
+
119
+ <div align="center">
120
+ <img src="https://github.com/YanMing-lxb/PyTeXMK/blob/main/imgs/show1.png?raw=true" alt="PyTeXMK 预览 1" width="45%" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
121
+ <img src="https://github.com/YanMing-lxb/PyTeXMK/blob/main/imgs/show2.png?raw=true" alt="PyTeXMK 预览 2" width="45%" style="border-radius: 8px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);">
122
+ </div>
123
+
124
+ ---
125
+
126
+ ## 🚀 快速开始
127
+
128
+ ### 前置条件
129
+
130
+ 在安装 PyTeXMK 之前,请确保你的系统已安装以下组件:
131
+
132
+ 1. **Python 3.14+**(通过 uv 管理推荐)
133
+ 2. **LaTeX 发行版**(任选其一):
134
+ - **Windows**: [MiKTeX](https://miktex.org/) 或 [TeX Live](https://tug.org/texlive/)
135
+ - **macOS**: [MacTeX](https://www.tug.org/mactex/) 或 BasicTeX
136
+ - **Linux**: TeX Live(发行版自带或官方安装)
137
+ 3. **可选工具**(按需安装):
138
+ - `biber`(biblatex 后端,用于参考文献处理)
139
+ - `xindy`(glossaries 后端,用于术语表编译)
140
+ - `latexdiff`(LaTeX 文件差异对比)
141
+
142
+ ### 安装
143
+
144
+ #### 通过 pip 或 uv
145
+
146
+ ```bash
147
+ # 使用 pip 安装
148
+ pip install pytexmk
149
+
150
+ # 使用 uv 安装(推荐)
151
+ uv add pytexmk
152
+ ```
153
+
154
+ #### Windows winget(推荐,无需 Python 环境)
155
+
156
+ ```powershell
157
+ winget install --id YanMing-lxb.PyTeXMK
158
+ ```
159
+
160
+ ### 升级
161
+
162
+ ```bash
163
+ # pip
164
+ pip install --upgrade pytexmk
165
+
166
+ # uv(升级到最新版)
167
+ uv add pytexmk@latest
168
+
169
+ # winget
170
+ winget upgrade --id YanMing-lxb.PyTeXMK
171
+ ```
172
+
173
+ ### 基本使用
174
+
175
+ 在 LaTeX 项目根目录下运行:
176
+
177
+ ```bash
178
+ # 使用默认配置(XeLaTeX + main.tex + Build/)编译
179
+ pytexmk
180
+
181
+ # 指定主文件编译
182
+ pytexmk main.tex
183
+
184
+ # 使用 PdfLaTeX 编译
185
+ pytexmk -p main.tex
186
+
187
+ # 编译 + 预览 PDF
188
+ pytexmk main.tex -pv
189
+
190
+ # 清理辅助文件
191
+ pytexmk -c
192
+ ```
193
+
194
+ > **注意**:PyTeXMK 仅支持 UTF-8 编码的 TeX 文件。
195
+
196
+ ---
197
+
198
+ ## ⚙️ 默认配置
199
+
200
+ | 配置项 | 默认值 | 说明 |
201
+ | --- | --- | --- |
202
+ | 编译程序 | `XeLaTeX` | 可选:XeLaTeX、PdfLaTeX、LuaLaTeX |
203
+ | 主文件名 | `main.tex` | 待编译的 LaTeX 主文件 |
204
+ | 输出目录 | `Build` | 编译结果存放目录 |
205
+ | 辅助目录 | `Auxiliary` | 辅助文件存放目录 |
206
+ | 编译模式 | batch 模式 | 编译过程不在终端显示详细日志 |
207
+
208
+ > **提示**:以上参数均可在配置文件中修改,详见 [配置文件说明](#配置文件说明)。
209
+ >
210
+ > **VSCode 用户**:在 `settings.json` 中设置 `"latex-workshop.latex.outDir": "./Build"` 以便 LaTeX-Workshop 找到 PDF 文件。
211
+
212
+ ---
213
+
214
+ ## 📖 使用说明
215
+
216
+ ### 编译引擎与模式
217
+
218
+ | 选项 | 说明 |
219
+ | --- | --- |
220
+ | `-p`, `--PdfLaTeX` | 使用 PdfLaTeX 编译 |
221
+ | `-x`, `--XeLaTeX` | 使用 XeLaTeX 编译(默认) |
222
+ | `-l`, `--LuaLaTeX` | 使用 LuaLaTeX 编译 |
223
+ | `-dr`, `--draft` | 草稿模式,编译时不包含图片(加速) |
224
+ | `-nq`, `--non_quiet` | 非安静模式,终端显示编译过程 |
225
+ | `-vb`, `--verbose` | 详细模式,显示 PyTeXMK 运行信息 |
226
+
227
+ ### 清理
228
+
229
+ | 选项 | 说明 |
230
+ | --- | --- |
231
+ | `-c`, `--clean` | 清除主文件的辅助文件 |
232
+ | `-C`, `--Clean` | 清除辅助文件(含根目录)和输出文件 |
233
+ | `-ca`, `--clean-any` | 清除所有带辅助文件后缀的文件 |
234
+ | `-Ca`, `--Clean-any` | 清除所有辅助文件(含根目录)和主文件输出 |
235
+
236
+ ### LaTeXDiff 差异对比
237
+
238
+ | 选项 | 说明 |
239
+ | --- | --- |
240
+ | `-d`, `--LaTeXDiff` | 生成两个文件的差异对比,输出 `LaTeXDiff.tex` |
241
+ | `-dc`, `--LaTexDiff-compile` | 生成差异文件并自动编译,输出带修订标记的 PDF |
242
+
243
+ **示例**:
244
+
245
+ ```bash
246
+ pytexmk -d old.tex new.tex # 生成 LaTeXDiff.tex
247
+ pytexmk -dc old.tex new.tex # 生成并编译 LaTeXDiff PDF
248
+ ```
249
+
250
+ > 支持在参考文献和符号索引中显示修改痕迹,编译时会提示选择风格。
251
+
252
+ ### PDF 工具
253
+
254
+ | 选项 | 说明 |
255
+ | --- | --- |
256
+ | `-pr`, `--pdf-repair` | 修复损坏的 PDF 文件(如图片导致的 `invalid X X R object` 警告) |
257
+ | `-pv`, `--pdf-preview` | 编译完成后调用浏览器或本地 PDF 阅读器预览 |
258
+
259
+ ### 多子项目管理
260
+
261
+ PyTeXMK 支持在一个项目根目录下管理多个相互独立的子项目,各自拥有独立的编译配置和输出目录。
262
+
263
+ **典型流程**:
264
+
265
+ ```bash
266
+ # 1. 生成根配置文件
267
+ pytexmk -i
268
+
269
+ # 2. 自动扫描并展示子项目清单(同时更新配置)
270
+ pytexmk -ls
271
+
272
+ # 3. 编译指定子项目(可与主文件名配合)
273
+ pytexmk -s 论文 main.tex
274
+ ```
275
+
276
+ | 选项 | 说明 |
277
+ | --- | --- |
278
+ | `-s`, `--subproject <名称>` | 选中指定子项目并在其目录下编译/清理 |
279
+ | `-ls`, `--list-subprojects` | 扫描子项目并展示清单,同步更新根配置 |
280
+
281
+ ### 配置文件生成
282
+
283
+ | 选项 | 说明 |
284
+ | --- | --- |
285
+ | `-i`, `--init` | 在当前目录生成项目级 `.pytexmkrc` |
286
+ | `-iu`, `--init-user` | 在用户主目录生成用户级 `.pytexmkrc` |
287
+ | `-f`, `--force` | 配合 `-i`/`-iu` 强制覆盖已存在的配置文件 |
288
+
289
+ ### 其他
290
+
291
+ | 选项 | 说明 |
292
+ | --- | --- |
293
+ | `document` | 位置参数,指定要编译的文件名(可省略后缀) |
294
+ | `-h`, `--help` | 显示帮助信息 |
295
+ | `-v`, `--version` | 显示程序版本号 |
296
+
297
+ ### 魔法注释
298
+
299
+ PyTeXMK 支持在 LaTeX 主文件前 50 行使用魔法注释来自定义编译行为:
300
+
301
+ | 魔法注释 | 说明 | 示例 |
302
+ | --- | --- | --- |
303
+ | `% !TEX program = <引擎>` | 指定编译引擎 | `% !TEX program = PdfLaTeX` |
304
+ | `% !TEX root = <文件名>` | 指定待编译主文件 | `% !TEX root = main` |
305
+ | `% !TEX outdir = <目录>` | 指定输出目录 | `% !TEX outdir = output` |
306
+ | `% !TEX auxdir = <目录>` | 指定辅助目录 | `% !TEX auxdir = auxfiles` |
307
+
308
+ > **注意**:魔法注释仅在主文件中定义有效,子文件中的注释会被忽略。
309
+
310
+ ### 工作原理
311
+
312
+ <details>
313
+ <summary><b>📂 主文件自动识别</b></summary>
314
+
315
+ 1. 命令行参数明确指定 → 使用该文件
316
+ 2. 当前目录仅一个 `.tex` 文件 → 自动选中
317
+ 3. 存在 `% !TEX root` 魔法注释 → 使用注释值
318
+ 4. 检索 `\documentclass` 或 `\begin{document}`(前 200 行)→ 识别主文件
319
+ 5. 默认回退到 `main.tex`
320
+
321
+ </details>
322
+
323
+ <details>
324
+ <summary><b>⚙️ 编译引擎选择</b></summary>
325
+
326
+ 1. 命令行参数 `-p` / `-x` / `-l` → 最高优先级
327
+ 2. 魔法注释 `% !TEX program` → 使用注释值
328
+ 3. 均未指定 → 默认 `XeLaTeX`
329
+
330
+ </details>
331
+
332
+ <details>
333
+ <summary><b>🔁 自动编译轮次</b></summary>
334
+
335
+ 1. 第一次编译 LaTeX
336
+ 2. 若 `.aux` 中存在参考文献引用,调度 bibtex / biber
337
+ 3. 若存在术语表/索引,调度 makeindex / xindy
338
+ 4. 继续编译 LaTeX,每轮结束后检测各维度是否收敛
339
+ 5. 所有维度稳定或达到安全上限后停止
340
+
341
+ </details>
342
+
343
+ ### 配置文件说明
344
+
345
+ PyTeXMK 支持两级配置文件,均为 TOML 格式:
346
+
347
+ | 类型 | Windows | Linux / macOS |
348
+ | --- | --- | --- |
349
+ | 用户级 | `C:\Users\用户名\.pytexmkrc` | `~/.pytexmkrc` |
350
+ | 项目级 | 当前目录 `.pytexmkrc` | 当前目录 `.pytexmkrc` |
351
+
352
+ **优先级**:项目级 > 用户级 > 内置默认值
353
+
354
+ 配置文件可通过 `pytexmk -i`(项目级)或 `pytexmk -iu`(用户级)生成模板,生成的模板中包含详细注释。
355
+
356
+ ---
357
+
358
+ ## 🛠 开发与构建
359
+
360
+ ### 环境要求
361
+
362
+ - Python 3.14+
363
+ - [uv](https://github.com/astral-sh/uv)(推荐)或 pip
364
+
365
+ ### 开发环境搭建
366
+
367
+ ```bash
368
+ # 克隆项目
369
+ git clone https://github.com/YanMing-lxb/PyTeXMK.git
370
+ cd PyTeXMK
371
+
372
+ # 安装开发依赖
373
+ uv sync --all-extras --dev
374
+
375
+ # 运行开发版本
376
+ uv run pytexmk --help
377
+ ```
378
+
379
+ ### 构建分发包
380
+
381
+ ```bash
382
+ # 构建 wheel 和 sdist
383
+ uv build
384
+ ```
385
+
386
+ ### 构建可执行程序
387
+
388
+ ```bash
389
+ # 生成平台图标
390
+ make icon
391
+
392
+ # 构建源码模式的可执行程序(onedir 目录)
393
+ make build
394
+
395
+ # 清理构建产物
396
+ make clean
397
+ ```
398
+
399
+ > **Windows 中的 make 命令**需要单独配置,详见 [Windows 下使用 make](docs/Window%20下使用%20make.md)。
400
+
401
+ ### 代码检查
402
+
403
+ ```bash
404
+ uv run ruff check src/
405
+ uv run ruff format src/
406
+ ```
407
+
408
+ ### 国际化工作流
409
+
410
+ ```bash
411
+ # 新增语言
412
+ make lang-add
413
+
414
+ # 更新所有 pot/po
415
+ make lang-update
416
+
417
+ # 编译 po → mo
418
+ make lang-mo
419
+
420
+ # 重新抽取所有 pot 模板
421
+ make lang-poup
422
+ ```
423
+
424
+ ---
425
+
426
+ ## 📄 许可证
427
+
428
+ 本项目基于 [GPLv3](LICENSE) 许可证开源。
429
+
430
+ ---
431
+
432
+ ## 📝 更新记录
433
+
434
+ 详细更新记录请参阅 [CHANGELOG.md](CHANGELOG.md)。
435
+
436
+ ---
437
+
438
+ ## 🤝 参与贡献
439
+
440
+ 欢迎提交 Issue 和 Pull Request!
441
+
442
+ - 🐛 遇到 Bug?请在 [Issues](https://github.com/YanMing-lxb/PyTeXMK/issues) 中提交
443
+ - 💡 有新功能建议?欢迎讨论
444
+ - 🌍 想帮助翻译?请查看 [国际化工作流](#国际化工作流)
445
+
446
+ ---
447
+
448
+ ## ⭐ Star History
449
+
450
+ [![Star History Chart](https://api.star-history.com/svg?repos=YanMing-lxb/PyTeXMK&type=Date)](https://star-history.com/#YanMing-lxb/PyTeXMK&Date)
451
+
452
+ ---
453
+
454
+ <div align="center">
455
+
456
+ **如果这个项目对你有帮助,欢迎点个 Star ⭐ 支持一下!**
457
+
458
+ </div>