2.7. 第一个 Sphinx 项目#
注意： 以下内容以 Windows 作为操作演示平台，macOS 上的操作基本一致。
前一小节我们利用 Anaconda 和 VS Code 搭建了一体化的 Sphinx 工作台，现在可以启动我们第一个Sphinx 项目了！
2.7.1. 创建项目#
Sphinx 提供了一个快速创建 Sphinx 项目的脚本 sphinx-quickstart，这个脚本相当于一个设置向导，它会询问我们一系列问题，并根据我们的回答生成此项目的文档源目录及默认配置文件 conf.py，如图所示：
提示： 所有的项目配置均可在之后通过项目配置文件 conf.py 修改。
完成上述步骤后，当前路径下会出现如下文件/文件夹：
.
├─ make.bat # Window下的编译脚本
├─ Makefile # Linux下的Makefile文件
├─ build # make编译后产生的导出文件目录
└─ source # 文档源码目录
├─ conf.py # 项目配置文件
├─ index.rst # 文档源文件入口
├─ _static # 用于存放参与编译的静态文件
└─ _templates # 用于存放项目的主题模板文件
现在我们已经成功创建了一个 Sphinx 项目文件，下面的步骤便是为你的项目添加内容与进行装饰了！
但在那之前，让我们看看尝试一下现在能否使用 Sphinx 导出些什么！在终端中输入make html，回车；
注意：
Powershell（Windows 下 VS Code 的默认终端）需要使用
.\make html，.\不可省略 。
make html会对 index.rst 及其关联文件进行编译，并在../build/html/目录下生成 HTML 项目包。
使用浏览器打开 ../learn-sphinx/build/html/目录下的 index.html 文件，可以看到一个由 Sphinx 生成的简单网页：
尽管我们还未向文档源文件目录中填充具体内容，但这个 “简陋的” 网页已经为我们展示了 Sphinx 生成网页的基本结构：
页面左侧显示了我们的项目名称，并具有导航页和搜索框；页面主体上方有欢迎语，下方是项目创建时间、文档创建说明和页面源文件的链接。
下面我们将学习如何组织我们的文档内容，包括撰写文本内容与定义文档结构。
2.7.2. 组织内容#
Sphinx 使用 reStructuredText 作为默认标记语言，通常我们可以在 source 目录下添加 chapter1.rst、chapter2.rst 等源文件，用于撰写文档的不同章节，并使用 index.rst 对其他 rst 文件进行组织管理。
提示：
index.rst 是由 Sphinx 的文档主入口，它可被转换成文档的欢迎页；
建议在 source 目录下新建一个 images 目录用于存放文档中需要插入的图片。
我们将在下一章学习 reStructuredText 的语法，现在先请同学们从本教程的 GitHub 仓库 中获取 chapter1.rst、chapter2.rst、basic_screenshot.png 等文件，并将它们存放在我们的 ../learn-sphinx/source 目录下。
完成后的目录结构如下所示：
.
├─ make.bat # Window下的编译脚本
├─ Makefile # Linux下的Makefile文件
├─ build # make编译后产生的导出文件目录
└─ source # 文档源码目录
├─ _static # 用于存放参与编译的静态文件
├─ _templates # 用于存放项目的主题模板文件
│
├─ images # 用于存放文档中需插入的图片
│ basic_screenshot.png # 图片文件
│
├─ chapter1.rst # 第一章文档源文件
├─ chapter2.rst # 第二章文档源文件
│
├─ conf.py # 项目配置文件
└─ index.rst # 文档源文件入口
完成添加 chapter1.rst, chapter2.rst 等文件后，我们还需要在 index.rst 将这些文件包含进来，并定义我们的文档结构，现在使用 VS Code 对 index.rst 里的 toctree 做如下修改：
.. toctree::
:maxdepth: 2
:caption: Contents:
:numbered:
chapter1
chapter2
其中，toctree 用来于产生目录表，numbered 表示章节编号，maxdepth 表示目录中只显示几层标题，之后空一行，在下面列出各 .rst 子文档，可以不加文件后缀，但要注意代码对齐，更多有关toctree 的内容可以参见 Sphinx 官方文档。
修改完成后，我们再一次在终端中使用 make html 命令，并在浏览器中打开 ../learn-sphinx/build/html/目录下的 index.html 文件，看看这次我们生成的网页有何不同！
2.7.3. 修改配置#
前一小节我们尝试了使用 Sphinx 默认配置发布了我们的 HTML 网页，现在我们来学习如何修改文档的格式与风格！
Sphinx 项目的配置由 conf.py 文件所控制，如果项目是通过 sphinx-quickstart 脚本创建的，conf.py 将会被自动创建，存放在 source 目录下。
如图所示，使用sphinx-quickstart 脚本自动创建的 conf.py 文件已经包含了该项目的一些基本属性和配置。我们可以通过修改 conf.py 的内容以修改 Sphinx 项目配置。
conf.py 中的配置主要包括项目信息、一般配置项以及 HTML 输出选项三大类：
项目信息 (Project information)#
由sphinx-quickstart脚本创建的 conf.py 文件已经包含了项目名称 (project)、版权声明 (copyright)、作者姓名 (author) 以及项目版本 (release) 等项目信息 (Project information)。
目前我们的项目属性（内容是对sphinx-quickstart若干问题回答）如下所示，：
此外，可以注意到 release 所在行之上的一条注释，实际上 release 指的是完整的项目版本，除了项目的主要版本 (version) 外，通常还包括 alpha/beta/rc 等标签，例如目前最新的 Python 文档版本号便是 3.9.0a2。
项目主要版本 (version) 也可单独作为一条属性添加在 conf.py 中，这样会在之后导出的文档中，在 version 和 release 之间提供分隔。
现在我们可对这些项目属性进行一些改动：
一般配置项 (General configuration)#
一般配置项 (General configuration) 的内容十分丰富，我们这里只介绍最常用的几个：
extensions: 配置 Sphinx 的扩展，内容是 extensions 模块下的字符串列表。
source_suffix: 定义源文件的文件扩展名，该值可以是字典映射文件扩展名到文件类型，默认为
source_suffix = {'.rst': 'restructuredtext'}。language: 文档编写的语言代码，Sphinx自动生成的任何文本都将使用该语言。目前 Sphinx 支持的语言及其代码可在 Sphinx 官方文档上查询到，我们平时比较常用的有英文和简体中文两种，其语言代码分别是
en与zh_CN。
练习1：为 Sphinx 项目添加 Markdown 支持#
提示：
Markdown 是一种与 reStructuredText 类似的标记语言，其语法甚至比 reStructuredText 更加简单一些。Markdown 是目前最受欢迎的标记语言，GitHub、Stack Overflow、reddit 以及知乎、简书等网站均支持这种格式。本教程的博客提供了一个 Markdown 简明教程，欢迎同学们学习！
Sphinx 默认仅支持 reStructuredText 标记语言，但我们可以通过安装 recommonmark 源解析器扩展使其支持添加 Markdown 标记语言。安装方法可参阅 Sphinx 官网文档。
请尝试为我们的 learn-sphinx 项目添加 Markdown 支持，并在原文档目录下添加一个由 index.rst 管理的 chapter3.md 文件（从本教程的 GitHub 仓库 获取该文件）。
步骤：
⑴ 首先，使用 conda 工具安装 recommonmark 扩展，在 Anaconda Prompt 中执行命令:
conda install recommonmark
**提示：**非 Anaconda 环境下可使用
pip install recommonmark安装 recommonmark 扩展。⑵ 然后，对 learn-sphinx 项目 conf.py 做如下修改：
extensions = ['recommonmark'] source_suffix = { '.rst': 'restructuredtext', '.txt': 'restructuredtext', '.md': 'markdown', }
这里我们通过添加
recommonmark扩展为 Sphinx 开启了 Markdown 支持，并将.rst和.txt映射到'restructuredtext'文件类型，将.md映射到 Markdown 文件类型。⑶ 接着，请同学们从本教程的 GitHub 仓库 获取 chapter3.md 文件，并将其存放在我们的 …/learn-sphinx/source 目录下。
⑷ 最后，修改 index.rst 文件，将 chapter3.md 添加到文件目录下：
特别注意： 在 index.rst 种引用 reStructuredText 文件时可省略
.rst扩展名，但引用 Markdown 文件时不可省略.md扩展名。为确保引用格式正确，建议在一个文档内引用不同格式文本时不省略.rst扩展名。
HTML 输出选项 (Options for HTML output)#
这些选项会影响 Sphinx 中 HTML 文档的输出，以及其他使用 Sphinx 的 HTMLWriter 类的文档构建器。
这里只介绍一个最常用的 html_theme ，该配置项会影响 Sphinx 编译输出 HTML 的主题风格，用户通过修改 html_theme 的值以修改 HTML 主题。
Sphinx 默认的 HTML 主题为 alabaster，alabaster 是 Sphinx 的内置主题之一，Sphinx 内置主题还包括 basic、classic、sphinxdoc、scrolls、agogo、nature、pyramid、haiku、traditional、epub、bizstyle 等 11 种。
此外，还有不少第三方主题（例如 sphinx_rtd_theme）可通过额外安装后使用，更多有关主题设置与定制的内容请参考 Sphinx 官方文档，之后的 “Sphinx 主题定制” 学习专题也会对此有进一步介绍。
练习2：为 Sphinx-HTML 网页换一种风格#
请在完成 练习1：为 Sphinx 项目添加 Markdown 支持 的基础上，修改 Sphinx 项目的 HTML 的主题为任一 Sphinx 内置主题，并将其发布。
本小节只介绍了一些比较常用的 Sphinx 项目配置属性，更多内容请参考 Sphinx 官方文档。
2.7.4. 发布文档#
在前面三个小节中，我们已经多次使用 make html 将我们的 Sphinx 项目发布成本地的 HTML 网页。
实际上，我们也可以使用 Sphinx 的 sphinx-build 命令达到相同的效果，删除先前用 make html 生成的../build/html/目录内的全部文件，然后在终端中输入下面这行命令：
sphinx-build -b html <sourcedir> <builddir>
# -b 是创建工具的选项，html 指创建的是 html 文件
# <sourcedir> 指项目的源目录，默认应填 source
# <builddir> 指导出文档的目录，默认应填 build
命令执行完成后，网页文件会存放在指定的导出目录下。实际上，make html 即是利用 Makefile 和 make.bat 批处理文件简化了 sphinx-build 的操作，两者在本质上基本相同。
教程第三部分的 “Sphinx 文档发布” 学习专题将进一步介绍如何使用 Sphinx 构建 PDF、LaTeX 等格式的文档，此专题还介绍了如何将 Sphinx 发布的网页托管至云端，以实现 HTML 文档的公网访问。
至此，同学们应已初步了解了文档代码化的基本思想，并着手创建、完善了自己的第一个 Sphinx 项目。下面我们还将学习 reStructuredText 和 Markdown 的基础语法，更多的进阶内容也将以学习专题的形式呈现，欢迎同学们继续学习！