文档制作工具Sphinx简介

1.9. 文档制作工具Sphinx简介#

该手册采用 reStructuredText 标记语言（ Markup Language ）撰写, 使用 Sphinx 进行发布.

1.9.1. 标记语言简介#

标记语言，是一种将文本以及文本相关的其他信息结合起来，展现出关于文档结构和数据处理细节的电脑文字编码。 文本相关的其他信息（包括文本的结构和表示信息等）与原来的文本结合在一起，但是使用标记进行标识。

标记语言是使用计算机编码的方式对文本内容进行组织的方法。自计算机工具出现已来，出现了大量的标识语言。

简而言之, 标记语言就是特定的标记符号集合, 每个特定标记符可以实现特定的功能（自己总结的）, 如倾斜、加粗、连接、引用等等, 如在reStructureText或者Markdown中, 使用星号括住文本, 可将文本渲染成斜体或粗体, 即 *我变斜了* 被渲染成 我变斜了, **我变粗了** 被渲染成 我变粗了 .

Markdown标记语言#

Markdown 的 设计哲学是易读（easy-to-read）易写（easy-to-write）, 是一种轻量级标记语言, 之所以称为轻量级是因为其标记符号集合较小, 容易记住和使用. Markdown标记语言, 如今被越来越多的写作爱好者和撰稿者广泛使用, 也被大多数现代网站所采用, 如 GitHub 、 StackOverflow 、 简书 、 CSDN 、 有道云笔记 、 Gitblog 等等。 此外, 很多开源项目的自述文件 README.md 也是采用Markdown语言编写的。

Markdown的语法手册可以参见：

由于Markdown的语法简单, 使得其共功能有限, 因而有了基于Markdown的各种语法扩展, 这里就不再细说, 有兴趣地话自行了解.

reStructuredText标记语言#

reStructuredText 是比Markdown功能更为强大但语法也更为复杂的一种标记语言. 配合Sphinx使用, 可以撰写渲染排版出优美的文档, 且输出格式丰富. 两者的介绍分别见： :ref: reStructuredTextSimpleTutorial 和 :ref: ChaSphinxSimpleTutorial .

标记语言的优点#

标记语言的撰写很简单, 不需要很高大上的IDE, 只需要一个能够编辑文字的文本编辑器即可, 完全可以只用Windows系统的“记事本”或者Linux上的“vi”来完成撰写。 这样的类似代码的语言，很容易使用诸如Git这样的版本控制系统进行管理！可以总结出以下优点：

  • 专注于文本内容而不是排版样式

  • 兼容所有文本编辑器与字处理软件

  • 可以使用Git等版本控制系统管理文章版本

  • 可读、直观、易学

使用标记语言需要会什么？#

  • 哈哈, 首先得知道写什么

  • 嘿嘿, 你得会打字

  • 正经的, 你必须学习一门标记语言的语法（如Markdown、reStructureText）

  • 工具1：你需要一个文本编辑器（notepad、vi、Sublime Text）

  • 工具2：你需要一个该标记语言的解释渲染器（太多了, 不同平台不一样, 如Sphinx）

让我们开始吧！！！

1.9.2. Sphinx 与 reStructuredText#

Sphinx 是种令人可以轻松撰写出优美文档的工具, 由 Georg Brandl 在BSD 许可证下创造, 它允许开发人员以纯文本格式编写文档, 以便采用满足不同需求的格式轻松生成输出. 这在使用 Version Control System 追踪变更时非常有用. 纯文本文档对不同系统之间的协作者也非常有用. 纯文本是当前可以采用的最便捷的格式之一.

虽然 Sphinx 是用 Python 编写的, 并且最初是为 Python 语言文档而创建, 但它并不一定是以语言为中心, 在某些情况下, 甚至不是以程序员为中心. Sphinx 有许多用处, 比如可以用它来发布你的项目文档, 或编写整本书！

Sphinx官网：http://www.sphinx-doc.org/en/stable/, 就是采用reStructuredText标记语言撰写, Sphinx发布的.

Sphinx具有以下亮点：

  • 丰富的输出格式：HTML（包括Windows HTML Help）, LaTex（用于可打印PDF）, epub, Texinfo, manual pages, plain text

  • 完备的交叉引用：语义化的标签, 并自动链接函式、类、引文、术语以及类似片段信息

  • 明晰的层级结构：轻松定义文档树, 并自动化链接同级/父级/下级文章

  • 美观的自动索引：自动生成索引以及特定语言模块的索引

  • 精确的语法高亮: 基于 Pygments 自动语法高亮

  • 开方的扩展: 支持代码片段的自动测试, 从Python模块的文档字符串包含（API文档）, 参考 more

  • 用户贡献的扩展: 用户提供的 大约50个扩展,大多可以通过PyPI安装

  • 强大简洁的书写语言: 使用 新结构化文本(reStructuredText) 作为标记语言.

目录