mathy-pydoc 完整使用手册一、包基础概述1. 核心定位mathy-pydoc是基于 Python 标准库pydoc二次封装、专为数学计算类项目打造的自动化文档生成工具适配含大量公式、数值函数、矩阵运算、符号计算的代码工程。原生pydoc对数学注释、LaTeX 公式、数值参数说明支持差该包做了增强解析 docstring 内 LaTeX 数学公式并渲染展示自动识别数学函数入参范围、定义域、单位、误差说明支持数学类、算子、迭代算法、微分积分函数分类归档输出增强 HTML/Markdown 文档内置数学公式渲染样式集成 mathy 符号计算库注释解析联动2. 核心功能清单增强文档提取兼容 Google/Numpy/ReST 三种数学风格 docstring自动提取定义域、边界条件、误差阈值、单位LaTeX 公式解析渲染识别$...$行内公式、$$...$$块公式导出文档自带 MathJax 渲染数学对象分类索引自动区分标量函数、矩阵算子、微分方程、拟合算法、随机数模块多格式输出终端交互式文档、纯文本、Markdown、带公式渲染 HTML代码语法校验检查数学函数注释缺失定义域、参数单位、公式说明并输出警告联动 mathy 库自动解析 mathy 符号表达式类型、化简规则、运算约束写入文档批量项目扫描递归遍历工程生成完整数学项目文档站API 可编程调用不依赖命令行可在 Python 脚本内动态生成文档内容。3. 依赖环境Python ≥3.8前置依赖mathy符号计算、jinja2HTML模板、markdown-mathmd公式、pygments代码高亮二、完整安装教程1. 标准 pip 安装# 稳定正式版pipinstallmathy-pydoc# 含完整数学渲染扩展推荐pipinstallmathy-pydoc[full]# 国内镜像加速pipinstallmathy-pydoc-ihttps://pypi.tuna.tsinghua.edu.cn/simple2. 源码安装最新开发版gitclone https://github.com/mathy/mathy-pydoc.gitcdmathy-pydoc pipinstall.[full]3. 验证安装importmathy_pydocprint(mathy_pydoc.__version__)# 输出版本号即安装成功三、核心语法、模块与参数详解3.1 顶层核心模块importmathy_pydoc# 核心类mathy_pydoc.MathyDoc# 文档生成主类mathy_pydoc.DocGenerator# 批量项目生成器mathy_pydoc.MathParser# LaTeX公式与数学注释解析器mathy_pydoc.Checker# 数学注释规范校验器3.2 MathyDoc 主类初始化参数核心classMathyDoc:def__init__(self,target,# 必填目标对象(模块/类/函数/文件路径)style:strnumpy,# docstring风格numpy/google/restrender_math:boolTrue,# 是否解析LaTeX公式mathjax_cdn:strNone,# 自定义MathJax CDN地址show_domain:boolTrue,# 是否展示参数数学定义域show_error_bounds:boolTrue,# 展示误差、精度说明sort_math_type:boolTrue,# 按数学类型分类函数ignore_private:boolTrue,# 忽略 _开头私有函数unit_tag:strunit,# docstring内单位标记关键字domain_tag:strdomain# 定义域标记关键字):3.3 MathyDoc 实例核心方法方法作用返回值get_text()生成纯文本数学文档strget_markdown()生成带公式MD文档strget_html(out_pathNone)生成带MathJax的HTML传路径直接写入文件str/Nonecheck_comments()校验数学注释完整性返回缺失项列表listlist_math_functions()提取所有数学函数并分类字典dict3.4 命令行全局参数终端调用# 通用命令格式mathy-pydoc[OPTIONS]TARGET关键命令行参数--style numpy指定注释风格--no-math关闭LaTeX公式渲染--html ./docs批量输出HTML文档到文件夹--md ./readme.md输出markdown文档--check仅校验注释规范不生成文档--recursive递归扫描整个项目包--all包含私有函数、内部算子3.5 支持的数学docstring语法规范以 Numpy 风格为例包默认推荐新增数学专用标记deflinear_func(x,k,b):一元一次线性函数 $y kx b$ Parameters ---------- x : float 自变量domain: $x \in \mathbb{R}$unit: m k : float 斜率domain: $k \neq 0$误差: $\pm 10^{-6}$ b : float 截距 Returns ------- y : float 输出结果单位米 Notes ----- 线性拟合核心公式 $$ y kx b $$ 专用标记关键字domain:后跟LaTeX定义域表达式unit:参数物理单位error:计算误差、精度阈值formula:单独标注核心计算公式四、8个完整可运行实际应用案例案例1单个数学函数生成Markdown文档需求解析一元二次求根函数输出带LaTeX公式md文档importmathy_pydocdefquadratic(a,b,c):一元二次方程求根 $ax^2bxc0$ Parameters ---------- a : float 二次项系数domain: $a \neq 0$ b : float 一次项系数 c : float 常数项 Returns ------- x1, x2 : tuple[float, float] 方程两个实数根 Notes ----- 求根公式 $$ x \frac{-b \pm \sqrt{b^2-4ac}}{2a} $$ deltab**2-4*a*c x1(-bdelta**0.5)/(2*a)x2(-b-delta**0.5)/(2*a)returnx1,x2# 生成文档docmathy_pydoc.MathyDoc(targetquadratic,stylenumpy)md_contentdoc.get_markdown()# 写入文件withopen(quadratic_doc.md,w,encodingutf-8)asf:f.write(md_content)print(MD文档生成完成)案例2数学类矩阵运算类生成HTML在线文档需求矩阵基础运算类输出可直接浏览器打开的带公式HTMLimportmathy_pydocclassMatrixCalc:二维矩阵基础运算工具类 Supports matrix add, multiply, determinant defdet(self,mat):二阶矩阵行列式计算 $$ det\begin{pmatrix}a b \\ c d\end{pmatrix}ad-bc $$ Parameters ---------- mat : list[list[float]] 2×2方阵domain: 仅支持二维方阵 Returns ------- res : float 行列式值 a,bmat[0]c,dmat[1]returna*d-b*c# 生成HTML文档并保存docmathy_pydoc.MathyDoc(targetMatrixCalc)htmldoc.get_html(out_path./matrix_docs.html)print(矩阵运算HTML文档已输出)案例3批量递归扫描整个数学项目生成文档站目录结构math_project/内含多个算法模块frommathy_pydocimportDocGenerator# 批量生成器genDocGenerator(root_path./math_project,output_dir./math_docs_site,recursiveTrue,render_mathTrue)# 执行批量构建自动生成索引页分模块HTMLgen.build_all()print(完整项目数学文档站构建完成)案例4注释规范校验定位缺失定义域/公式的函数importmathy_pydocdefbad_func(x):无定义域、无公式注释的劣质数学函数returnx**2docmathy_pydoc.MathyDoc(targetbad_func)# 校验注释返回缺陷列表errorsdoc.check_comments()forerrinerrors:print(f注释缺陷{err})# 输出参数x缺少domain定义域说明、无核心公式标注案例5联动 mathy 符号表达式解析并写入文档importmathyimportmathy_pydocdefsymbolic_simplify(expr:mathy.Expression):符号表达式化简 使用mathy库化简多项式 Parameters ---------- expr : mathy.Expression 输入符号多项式domain: 整式多项式 Returns ------- simplified : mathy.Expression 最简标准形式 Example ------- e mathy.parse(2x 3x) symbolic_simplify(e) 5x returnexpr.simplify()# 自动识别mathy类型并补充文档说明docmathy_pydoc.MathyDoc(targetsymbolic_simplify)print(doc.get_text())案例6命令行批量导出项目文档脚本调用cli接口frommathy_pydoc.cliimportmainaspydoc_cli# 等价终端命令mathy-pydoc --recursive --html ./docs ./my_math_libpydoc_cli([--recursive,--html,./docs,./my_math_lib])案例7关闭公式渲染仅生成纯文本轻量化文档适用于服务器无前端渲染场景importmathy_pydocdefintegral_approx(x_list):梯形法数值积分 Parameters ---------- x_list : list 离散采样点domain: 升序实数数组 pass# 关闭LaTeX渲染docmathy_pydoc.MathyDoc(targetintegral_approx,render_mathFalse)plain_textdoc.get_text()print(plain_text)案例8自定义MathJax CDN离线部署HTML文档内网环境无法访问公共CDN本地引入MathJaximportmathy_pydocdefgauss_dist(x,mu,sigma):高斯分布概率密度 $$ f(x) \frac{1}{\sigma\sqrt{2\pi}}e^{-\frac{(x-\mu)^2}{2\sigma^2}} $$ pass# 指定本地MathJax路径docmathy_pydoc.MathyDoc(targetgauss_dist,mathjax_cdn/static/mathjax/MathJax.js)doc.get_html(out_path./gauss_doc.html)五、常见错误、报错原因与解决方案1. ImportError: No module named ‘mathy_pydoc’原因未安装完整包仅装了基础pydoc解决pip install mathy-pydoc[full]2. LaTeX公式在HTML中空白不渲染原因1网络无法访问默认MathJax CDN方案初始化时传入本地mathjax_cdn路径原因2公式语法错误未成对、非法数学符号方案检查docstring内‘、非法数学符号 方案检查docstring内、非法数学符号方案检查docstring内‘$成对LaTeX语法规范原因3初始化参数render_mathFalse方案手动设render_mathTrue3. check_comments() 大量误报 domain 缺失原因自定义定义域标记关键字和默认domain不匹配解决初始化时修改标记domain_tag定义域注释内使用定义域: $x0$4. 批量DocGenerator递归扫描跳过部分py文件原因文件以_开头默认忽略私有模块解决构建生成器时传入参数ignore_privateFalse5. 导出Markdown无公式仅原始LaTeX文本原因缺少markdown-math依赖解决重装完整扩展pip install mathy-pydoc[full]6. 解析mathy.Expression时报类型识别失败原因未单独安装mathy符号库解决pip install mathy7. HTML导出报错 jinja2.TemplateNotFound原因包安装不完整内置HTML模板丢失解决卸载重装pip uninstall mathy-pydoc pip install mathy-pydoc[full]8. 函数传参为文件路径时报找不到模块错误代码MathyDoc(target./math_func.py)原因路径导入需要先将目录加入Python环境变量修复importsys sys.path.append(.)docmathy_pydoc.MathyDoc(targetmath_func)# 传入模块名而非文件六、使用注意事项与最佳实践1. Docstring 编写规范数学公式统一使用$行内$/$$块公式$$不混用其他标记所有数值参数必须标注domain定义域避免校验告警物理计算函数补充unit单位误差算法补充error复杂多公式拆分到Notes区块不要挤在单行说明。2. 项目工程使用规范数值计算包统一使用numpy注释风格兼容性最好线上文档部署使用自定义本地MathJax避免CDN加载失败CI/CD流水线中加入mathy-pydoc --check作为代码门禁强制完善数学注释大型项目拆分DocGenerator分模块生成避免单次扫描卡顿。3. 性能与兼容性限制超大型工程500个数学函数批量生成建议分批次执行Python3.7及以下版本不支持最低3.8复杂嵌套矩阵、多重积分长公式渲染速度较慢可拆分简化不支持原生Jupyter Notebook单元格注释仅解析.py源码文件。4. 安全注意事项不要解析外部不可信第三方代码文件解析过程会动态导入目标模块存在执行风险内网离线文档务必替换公共MathJax CDN防止外部网络请求泄露导出HTML文档不要暴露项目内部误差阈值、算法核心参数等敏感数值。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。