菜单导航

使用 sphinx 制作简洁而又美观的文档

作者: 精装之家 来源: 精装之家 发布时间: 2019年10月17日 06:18:42

使用 sphinx 制作简洁而又美观的文档

使文档变得更有效并且可编写

Alfredo Deza
2012 年 1 月 18 日发布

简介

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

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

突出显示

默认情况下,Sphinx 会为 Python 突出显示代码,但它还允许定义其他编程语言,比如 C 和 Ruby。

可以将 Sphinx 想像成为一种文档框架:它会抽象化比较单调的部分,并提供自动函数来解决一些常见问题,比如突出显示标题索引和特殊代码(在显示代码示例时),以及突出显示适当的语法。

要求

您应该能轻车熟路地使用 Linux® 或 UNIX® 终端(也称为控制台或终端仿真器),因为命令行界面是与 Sphinx 进行互动的主要方式。

您需要安装 Python。在所有主要的 Linux 发行版和一些基于 UNIX 的操作系统(如 Mac OSX)上预先安装 Python 并做好使用它的准备。Sphinx 支持 Python V 2.4、2.5 和 2.6。要确定您已经安装了 Python 并且安装的是有效版本,请运行 中的代码。

清单 1. 检查 Python 的版本$ python --version Python 2.6.1语法

Sphinx 使用 reStructuredText 标记语法(和其他一些语法)来提供文档控制。如果您之前编写过纯文本文件,那么您可能非常了解精通 Sphinx 所需的语法。

标记允许为适当的输出实现文本的定义和结构。开始之前,请参见 中的一个小的标记语法示例。

清单 2. Sphinx 标记语法示例This is a Title =============== That has a paragraph about a main subject and is set when the '=' is at least the same length of the title itself. Subject Subtitle ---------------- Subtitles are set with '-' and are required to have the same length of the subtitle itself, just like titles. Lists can be unnumbered like: * Item Foo * Item Bar Or automatically numbered: #. Item 1 #. Item 2 Inline Markup ------------- Words can have *emphasis in italics* or be **bold** and you can define code samples with back quotes, like when you talk about a command: ``sudo`` gives you super user powers!

正如您所看到的,纯文本格式的语法非常容易读懂。在创建特定格式(如 HTML)时,标题会成为主要目标,其字体会比副标题大一些(理应如此),并且会对编号列表进行适当的编号。您已经拥有一些非常强大的功能。添加更多的项或更改编号列表中的顺序不会影响到编号,而通过替换使用的下划线可以改变标题的重要性。

安装和配置

安装是通过命令行进行的,非常简单明了,如 所示。

清单 3. 安装 Sphinx$ easy_install sphinx Searching for sphinx Reading Reading Best match: Sphinx 1.0.5 Downloading [...] Processing Sphinx-1.0.5-py2.5.egg [...] Finished processing dependencies for sphinx

为了简便起见, 中的内容有所缩减,但它提供了在一个在安装 Sphinx 时应执行的操作的示例。

框架使用了一个目录结构来分离源文件(纯文本文件)和构建(指生成的输出)。例如,如果使用 Sphinx 从文档源中生成一个 PDF,那么该文件会放置在构建目录中。您可以更改此行为,但为了获得一致性,我们还是保留了默认格式。

让我们快速启动 的一个新的文档项目,系统会通过一些问题提示您如何操作。请按下 Enter 键接受所有的默认值。

清单 4. 执行 sphinx-quickstart$ sphinx-quickstart Welcome to the Sphinx 1.0.5 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). [...]

我选择 "My Project" 作为项目名称,该名称会在多处被引用。您可以随意选择不同的名称。

运行 sphinx-quickstart 命令后,在工作目录中会出现类似 的文件。

清单 5. 工作目录的列表. ├── Makefile ├── _build ├── _static ├── conf.py └── index.rst

让我们详细研究一下每个文件。