使用Sphinx在CentOS 7上以多种格式创建文档

• 先决条件
• 步骤1：更新系统
• 步骤2：安装pip和Sphinx
• 步骤3：设置文档的基本配置
• 步骤4：为文档构建层次结构
• 步骤5：创建上面指定的源文件
• 步骤6：输出文档的HTML版本

Sphinx是技术人员和作家使用的基于Python的有用工具，使他们可以轻松创建各种格式的精美，功能齐全的文档。使用Sphinx，您可以使用reStructuredText（一种轻量级的标记语言）为初学者编写文档，然后可以获得多种格式的输出，包括HTML，LaTeX，PDF，ePub等。

在本教程中，我们将介绍Sphinx在Vult平台上的CentOS 7 x64实例上安装和使用的过程。

先决条件

• 一个CentOS 7 x64实例。
• 一个sudo的用户。

步骤1：更新系统

sudo yum update
sudo shutdown -r now

步骤2：安装pip和Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

步骤3：设置文档的基本配置

在开始使用之前Sphinx，您需要指定将在其中Sphinx运行并保存所有文档的源目录。一旦创建了要使用的目录，就可以运行sphinx-quickstart它将初始化Sphinx并创建所需的基本配置。

sphinx-quickstart 与安装向导类似，该向导将提示您有关确定项目各个方面的问题。

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

步骤4：为文档构建层次结构

默认情况下，该sphinx-quickstart向导将创建多个目录和文件。

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

让我们看一下主文件index.rst，它包含文档的层次结构；即目录树或目录toctree。

用文本编辑器打开它：

vi index.rst

查看文件时，您会注意到一个名为的部分toctree。如果您*.rst的文档还有其他源文件（），则需要在以下toctree部分中指定它们：.. toctree ::：：maxdepth：2

   introduction
   chapter1
   chapter2
   chapter3
   more

当务之急是：

• 在输入上方保留空白行。
• 不要在源文件后缀.rst。
• 将源文件按各自的顺序放置。
• 每行仅使用一个文件名。
• 用缩进文件名:maxdepth: 2。

完成修改后，保存文件并退出文本编辑器。

ESC
:!wq

步骤5：创建上面指定的源文件

必须使用与先前在中指定的名称匹配的名称创建源文件index.rst，否则它们将不包含在最终输出中。

所有源文件都必须与兼容reStructuredText markup language。有关更多信息，请参考reStructuredText Primer。

步骤6：输出文档的HTML版本

完成文档的编写后，您可以HTML format 通过执行以下命令来输出您的工作：

make html

输出将保存在目录中./\_build/html，该目录包含在Web浏览中查看文件所需的所有内容。

到此结束我们的教程。