Sphinx文档管理与构建

Sphinx文档管理与构建#

注解

构建工具版本：

  • Python: 3.9.2 (default, Mar 20 2025, 02:07:39)

  • Sphinx: 7.4.7

  • Sphinx book theme: 1.1.4

  • MyST: 3.0.1

构建时间： 2025 年 06 月 12 日

根据多年来进行文档处理、文档编写的经验整编而成。 目前有大量的工具可用于文档的管理与处理，工具的使用，与其说是好坏，不如说是选择， 是与使用人的性格、方式、观点等密切相关的。 因此，文档中给出的一些实践方式与观点，读者可以了解、探讨。

主体内容以 Sphinx 和 reStructuredText 为主, 利用这些工具可以很容易的做出功能完备的文档。 Sphinx是用于创建文档的流行应用程序，如HTML、PDF， 借助一些工具还可以导出Latex、epub等文件。 另外，借助于其强大的扩展功能，可以当成一种网站框架来使用，实现超越文档发布的复杂应用功能。

内容力求简明，包含但不限于如下内容：

  • Sphinx使用介绍

  • reStructuredText语法说明

  • Markdown及扩展语法说明

  • 与Sphinx相关的一些工具

文档代码化 (Docs as Code)，是一种新兴的的技术文档开发模式，即使用代码开发的方式和工具进行文档开发。

文档代码化意味着将文档开发融入产品开发的工作流程，可有效节省工具成本，提升文档开发效率，并增强产品研发和文档写作的协同管理。

目前，微软、亚马逊和阿里等高科技公司已逐渐将文档代码化应用于生产实践，其文档开发流程大致包括五大步骤：

  • 使用 Markdown、reStructuredText 等标记语言写作；

  • 通过 Git 进行版本管理和协同写作；

  • 使用代码开发集成环境作为写作工具；

  • 通过文档发布工具将 Markdown、reStructuredText 文件发布为网页或PDF等格式；

  • 收集文档的用户使用数据，不断迭代改进文档质量。

该手册采用reStructuredText标记语言撰写，使用Sphinx进行发布。

参考项目

另外在文字内容整理过程中还参考了更多的网页内容， 由于前期没有做好完备的记录，因此这里无法列出，敬请谅解。

索引

索引

目录