如何快速搭建 Python 项目脚手架MILQ 模板中的 Sphinx 文档体系与模块化组织完整指南【免费下载链接】milqUseful code of Manuel Ignacio López Quintero项目地址: https://gitcode.com/gh_mirrors/mi/milqMILQ 是 Manuel Ignacio López Quintero 分享的实用代码集其中templates/python/目录内置了一套开箱即用的Python 项目脚手架完整的Sphinx 文档体系、按功能分层的模块化包组织、可运行的示例与测试目录。本指南带你从零看懂这套模板5 分钟就能搭建出自己的文档化 Python 项目。 获取模板git clone https://gitcode.com/gh_mirrors/mi/milq 项目脚手架目录结构一眼看懂 Python 模板组织目录作用doc/Sphinx 文档源码、构建配置与 Makefilemy_module/业务包本体模块化组织的核心examples/demo.py可直接运行的示例脚本tests/测试代码目录data/数据文件目录这种文档、代码、示例、测试、数据分离的布局正是 Python 开源项目的主流脚手架形态照抄即可。 模块化包设计从 operations 到 laws 的分层思路模板中的 my_module 演示了一套经典的分层组织方式operations/elementary.py基础层提供add、subtract、multiply、divide四个基础运算operations/exponentiation.py在基础层之上实现square、cubelaws/gravitation.py应用层复用下层函数实现牛顿万有引力公式两个关键细节值得学习每个包都有__init__.py其中用模块级 docstring 描述包职责例如my_module/__init__.py里就写明文档以代码内 docstring 形式提供每个函数都带 docstring如multiply的注释说明了参数a与b的含义这些注释正是 Sphinx 自动生成文档的素材。 分层原则底层通用、上层专用上层只 import 下层避免循环依赖。 Sphinx 文档体系conf.py 关键配置解析文档配置位于 doc/src/conf.py新手只需关注 4 处sys.path.insert(0, os.path.abspath(../../)) # ① 让 autodoc 找到代码包 extensions [sphinx.ext.autodoc, sphinx.ext.doctest] # ② 自动文档 文档测试 project my_module # ③ 项目名 html_theme sphinx_rtd_theme # ④ 经典 Read the Docs 主题① sys.path 注入把上级目录加入模块搜索路径autodoc 才能解析到my_module② autodoc 扩展直接读取代码里的 docstring 生成 API 参考页代码即文档④ RTD 主题conf.py 中通过sphinx_rtd_theme.get_html_theme_path()启用文档页面专业又美观。文档入口是 doc/src/index.rst用toctree指令组织页面树并挂载genindex全局索引与search搜索页。 Sphinx 文档快速构建步骤从 apidoc 到 make html按 doc/src/README.rst 的说明标准流程只有三步生成 API 页面在doc/src/下运行sphinx-apidoc -o . ../../my_module自动生成modules.rst与包对应的 rst 文件挂接到目录树把生成的modules.rst加入index.rst的toctree一键构建 HTML在 doc/Makefile 中执行make html产物输出到build/html/。Makefile 还内置了 20 多种构建目标singlehtml单页 HTML、epub、latex、linkcheck外链检查、doctest运行文档中的可执行示例等。Windows 用户可使用同目录下的 make.bat。 示例与测试目录的规范用法示例examples/demo.py 只 import 包内接口universal_gravitation_of_newton并打印结果是新用户学习 API 的最佳入口测试tests/目录预留测试用例位置配合sphinx.ext.doctest扩展文档示例还能顺带成为测试数据data/目录集中存放样例数据避免数据文件散落各层。✅ 快速上手清单5 分钟搭建你的文档化项目复制templates/python/作为项目骨架把包名my_module全局替换为你的项目名记得同步改conf.py里的project与htmlhelp_basename按基础层 → 应用层组织你的模块并为每个函数写好 docstring运行sphinx-apidoc生成 API 文档再执行make html验证文档效果在examples/写一个最小可运行示例作为 README 的快速开始。小结MILQ 的 Python 模板用最少的文件覆盖了项目脚手架的全部关键要素——模块化包分层、docstring 驱动的 Sphinx 文档体系、示例与测试目录。掌握这套结构你的第一个开源级 Python 项目就已成型。【免费下载链接】milqUseful code of Manuel Ignacio López Quintero项目地址: https://gitcode.com/gh_mirrors/mi/milq创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考