Sphinx文档管理与构建#
备注
工欲善其事，必先利其器。
根据作者多年来进行文档处理、文档编写的经验而成。 工具的使用，与其说是好坏，不如说是选择， 是与使用人的性格、方式、观点等密切相关的。 因此，文档中给出的一些实践方式，观点，读者可以了解、探讨。
主体内容以 Sphinx 和 reStructuredText 为主, 利用这些工具可以很容易的做出功能完备的文档。 Sphinx是用于创建文档的流行应用程序，如HTML、PDF， 借助一些工具还可以导出Latex、epub等文件。
另外，借助于其强大的扩展功能，可以当成一种网站框架来使用，实现超越文档发布的复杂应用功能。
内容力求简明，包含但不限于如下内容：
Sphinx使用介绍
reStructuredText语法说明
与Sphinx相关的一些工具
文档代码化 (Docs as Code)，是一种新兴的的技术文档开发模式，即使用代码开发的方式和工具进行文档开发。
文档代码化意味着将文档开发融入产品开发的工作流程，可有效节省工具成本，提升文档开发效率，并增强产品研发和文档写作的协同管理。
目前，微软、亚马逊和阿里等高科技公司已逐渐将文档代码化应用于生产实践，其文档开发流程大致包括五大步骤：
使用 Markdown、reStructuredText 等标记语言写作；
通过 Git 进行版本管理和协同写作；
使用代码开发集成环境作为写作工具；
通过文档发布工具将 Markdown、reStructuredText 文件发布为网页或PDF等格式；
收集文档的用户使用数据，不断迭代改进文档质量。
该手册采用reStructuredText标记语言撰写，使用Sphinx进行发布。
参考项目
学习Sphinx的文档 ： 介绍了绘图工具
reStructuredText 简介 ：这里面对数学表达式有较深入说明
尤金的一己之见 ：参考MyST相关内容。
Jupyter笔记 ：参考基于Jupyter Notebook的文档制作。
文档代码化 (Sphinx) 教程 : 对于文档代码化的介绍。
另外在文字内容整理过程中还参考了更多的网页内容， 由于前期没有做好完备的记录，因此这里无法列出，敬请谅解。
提示
构建时间 2025 年 04 月 29 日
索引
目录