13.2. Sphinx 开发环境配置

参考 Sphinx 的官方文档，配置 Sphinx 开发环境主要包括安装 Python 开发环境、 使用 pip 工具安装 sphinx 、安装配置文本、代码编辑器等步骤，同时还涉及到使用命令行和修改系统环境变量等操作。 这些步骤对于初学者来说略有些复杂繁琐，很容易就迷失在各种琐碎的配置细节中，打击同学们的学习热情。

不过 Python 社区始终有一批能人志士在为简化和优化开发环境配置而作各种努力，Anaconda 就是其中相当出色一个。 下面将会介绍如何通过 Anaconda 和 VS Code 在 Windows 和 macOS 两大操作系统上配置 Sphinx 开发环境，同学们可以根据自己使用的操作系统查看相应的部分。

• Anaconda 是一个开源的 Python 发行版，支持 Windows、macOS、Linux，Anaconda 是一个打包的集合，

• 里面预装好了conda、Python 解释器、众多第三方库（比如 Sphinx）、科学计算工具等等，其核心功能是由 conda 提供的包管理与环境管理功能。

• Visual Studio Code (VS Code) 是由 Microsoft 公司开发的新一代代码编辑器，

• 支持 Windows、macOS、Linux，将代码编辑器、调试器、终端等工具整合于一体，具有语法高亮、代码补全、括号匹配等功能，支持版本管理和远程开发，并拥有丰富的拓展生态。

---

13.2.1. Windows 环境配置

注意：

• 以下步骤不需要同学们预先安装 Python 解释器（如果之前有安装也可以考虑将其卸载），而是直接使用 Anaconda 内集成的 Python 解释器，如果同学们先前已经安装过单独的 Python 解释器（运行 Sphinx 必须预先安装 Python 3.5 及以上版本），可直接在命令行中使用命令 pip install sphinx 安装 Sphinx 及运行 Sphinx 所需要的 docutils、jinja2 等第三方库（前提是 Python 和 Pip 已添加在系统变量的 path 中）。

• 推荐同学们优先使用 Anaconda 来完成 Sphinx 开发环境配置，因为 conda 将几乎所有的工具、第三方库都当做 package 对待，甚至包括 python 和 conda 自身，它可以帮助我们方便地管理自己的 Python 开发环境，不仅能够将不同开发项目所依赖的开发环境完全独立开来，还可轻易地复制整个 Python 环境到其他机器上。

Anaconda 安装与配置

Ⅰ. 打开 Anaconda 官方下载页，下载适合的安装包：

提示： 如果官网下载速度较慢，可到清华大学开源软件镜像站下载 Anaconda 安装包。

Ⅱ. 下载完成后，运行可执行文件进行安装：

注意：

⑴ Anaconda 需要占用较大的存储空间，可考虑安装在非系统盘。

⑵ 请在 “Advanced Options” 中将勾选两个可选选项：

• 第一个选项 会将 Anaconda 的安装目录添加至系统环境变量的 path 中，有利于我们之后在 VS Code 中快速激活 conda 环境，以及直接使用 base 环境中已安装的库和脚本，简化操作流程，若是在安装过程中没有勾选此选项，需要自行添加系统环境变量，即添加Anaconda的安装路径以及到path。

① 如上图红字所示，Anaconda 官方不建议勾选此选项，而建议使用 Anaconda Prompt (或 Anaconda Powershell Prompt，以下将两者统称为 Anaconda Prompt) 。这是因为勾选此选项会将 Anaconda 的若干目录添加至 path 目录中的最前面；如果用户之前已经安装了其他 Python 解释器，勾选此选项会导致用户直接调用 Python 时优先调用 Anaconda 内置的 Python 解释器，而不是用户单独安装的 Python 解释器，如下图所示：

②（可选）假如同学们依然希望系统默认调用先前单独安装的 Python 解释器，只需要在完成Anaconda 安装后，手动将 path 中单独安装的 Python 解释器的路径移动到 Anaconda 目录之前，操作方法如下：

③ 此时，在命令行调用 Python 时会优先调用单独安装的 Python 解释器，只有在激活 conda 环境后才会调用 conda 里的 Python 解释器。（可以看到两个 Python 解释器的版本和版权说明有所区别）

• 第二个选项 可使其他 Python 开发工具（如 VS Code）自动探测到 Anaconda。

Ⅲ. 完成 Anaconda 的安装后，检查 Sphinx 是否已安装。

点击 “开始” 菜单 - “Anaconda3” - “Anaconda Powershell Prompt”，输入 conda list ，回车；

此指令会列出当前 conda 环境 (base) 下所有已安装的包，正常情况下我们可看到若干以 Sphinx 开头的包：

（可选） Anaconda 通常数月才更新一次，但其内部包含的包通常具有更快的更新频次，可使用 Anaconda 的包管理器对包进行单独更新。在 Anaconda Prompt 中输入 conda update sphinx 单独对 Sphinx 进行更新，但考虑到我们是第一次使用 Anaconda，更加推荐使用 conda update --all 命令对该环境下所有包都进行一次更新：

注意：conda update --all 命令执行中途需要手动输入一次 y 以确认更新操作，整个过程需要一段时间，当命令行最后一行显示 done 时，更新完毕，即可关闭命令行窗口。

提示： Anaconda 的默认软件镜像源位于国外，可通过修改 Anaconda 软件镜像源的方式解决在国内可能会遭遇的网络访问不稳定，下载速率慢等问题。（推荐使用清华大学开源软件镜像站的 Anaconda 镜像）

具体操作步骤如下：

​ ① 打开 ”开始“菜单 - “Anaconda3” - “Anaconda Prompt”，输入 conda config --set show_channel_urls yes 回车，该命令会在用户文件夹下创建 .condarc 文件；

​ ② 进入用户文件夹，使用记事本打开.condarc 文件，将其中内容替换为如下内容：

ssl_verify: true
channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  msys2: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  bioconda: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  menpo: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  pytorch: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
  simpleitk: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud

​ ③ 保存并退出.condarc 文件。

---

Visual Studio Code 安装与配置

Ⅰ. 打开 Visual Studio Code 官网，下载适合的安装包：

Ⅱ. 下载完成后，运行可执行文件进行安装，其安装过程与 Anaconda 安装过程相似：

注意： 请在安装程序的 “选择其他任务” 页中将所有复选框勾选上。

Ⅲ. 完成安装后打开 VS Code，在 Extentions 中安装 Python 和 reStructuredText 拓展。

---

VS Code 调用 Sphinx (Anaconda)

完成以上步骤后，已经基本搭建好了一个基于 Anaconda 和 VS Code 的一体化 Sphinx 工作台。在这一环节中，同学们可以检测自己的 Sphinx 开发环境， 为下一节 “第一个 Sphinx 项目” 做好准备。

Ⅰ. 在计算机任意位置新建一个文件夹，命名为 learn-sphinx，右击文件夹单击 “通过 Code 打开”。文件夹会显示在左侧边栏，下一小节创建项目的文件将会储存在这个文件夹。

Ⅱ. 打开 VS Code 窗口的集成 Terminal，输入 sphinx-build --version 回车。如下所示：

如果一切正常，同学们将会看到已安装 Sphinx 版本号（这里显示的版本是 |sphinx_version| ），这说明 Sphinx 开发环境已正确部署至计算机。

现在请移步到下一小节学习如何创建第一个 Sphinx 项目。

13.2.2. macOS 环境配置

在mac上配置 Sphinx，可以通过 Anaconda，Homebrew，MacPorts 等方式来完成，这里介绍使用 Anaconda，Pip，和 Homebrew 完成 Sphinx 安装与配置，三种方式选其一即可。

这三种相同点在于都是软件包管理工具，不同点在于 Homebrew 是一个通用的软件包管理工具，终端安装的很多软件包都可以用它来安装；Pip 一般安装一些与 Python 环境相关的软件包，conda 功能与 Pip 类似，目的是为了解决对 Python 以外的依赖环境问题，Pip 在任何环境中安装 Python 包; conda 在 conda 环境中装任何包。

Anaconda 安装与配置 （推荐）

注意：

• 以下步骤不需要同学们预先安装 Python 解释器，而是直接使用 Anaconda 内集成的 Python 解释器；

• 如果同学们先前已经安装过单独的 Python 解释器（运行 Sphinx 必须预先安装 Python 3.5 及以上版本），可查看下一小节 - 使用 Pip 安装 Sphinx；

• 更加推荐使用 Anaconda 来完成 Sphinx 开发环境配置，因为 conda 将几乎所有的工具、第三方库都当做 Package 对待，甚至包括 Python 和 conda 自身，它可以帮助我们方便地管理自己的 Python 开发环境，不仅能够将不同开发项目所依赖的开发环境完全独立开来，还可轻易地复制整个 Python 环境到其他机器上。

Ⅰ. 打开 Anaconda 官方下载页，下载适合的安装包：

提示： 如果官网下载速度较慢，可到清华大学开源软件镜像站下载 Anaconda 安装包。

Ⅱ. 下载完成后，运行可执行文件进行安装。

注意： 请在 “Advanced Options” 中将勾选 Add Anaconda to my PATH environment variable 和 Register Anaconda as my defaylt Python 3.7 两个可选选项：

• 第一个选项 会将 Anaconda 的安装目录添加至系统环境变量的 path 中，有利于我们之后在 VS Code 中快速激活 conda 环境，以及直接使用 base 环境中已安装的库和脚本，简化操作流程。

  • Anaconda 官方不建议勾选此选项，而建议使用 Anaconda Prompt (或 Anaconda Powershell Prompt，以下将两者统称为 Anaconda Prompt) 。这是因为勾选此选项会将 Anaconda 的若干目录添加至 path 目录中的最前面；如果用户之前已经安装了其他 Python 解释器，勾选此选项会导致用户直接调用 Python 时优先调用 Anaconda 内置的 Python 解释器，而不是用户单独安装的 Python 解释器，如下图所示：

    

• 第二个选项 可使其他 Python 开发工具（如 VS Code）自动探测到 Anaconda。

Ⅲ. Anaconda 预装了 Sphinx。完成 Anaconda 安装后，可检查一下 Sphinx 的安装情况：

点击启动台-其他-终端，输入conda list，回车，此指令会列出当前 conda 环境 (base) 下所有已安装的包，正常情况下可以看到若干以 Sphinx 开头的包：

Ⅳ. （可选） Sphinx 预装在 Anaconda 的默认环境下，同学们可以进一步通过 Anaconda Navigator 中检查 Sphinx 包配置情况，安装更多的包。

**提示 ：**Anaconda 通常数月才更新一次，但其内部包含的包通常具有更快的更新频次，可使用 Anaconda 的包管理器对包进行单独更新。这里可通过 Anaconda Prompt 输入命令行操作，也可以通过 Anaconda Navigator 进行可视化操作，相对上手更快。

点击启动台 - Anaconda Navigator，左侧菜单选择 Environments，检索框输入 Sphinx ，得到以下列表：

进一步勾选，点击右下角 Apply 进行安装。

Pip 安装与配置

Ⅰ. 使用 Pip 配置 Sphinx 也是方便快捷的方式。如果同学们先前安装过单独的 Python 解释器（运行 Sphinx 必须预先安装 Python 3.5 及以上版本），可直接使用第4步中的命令行安装 Sphinx。

提示：如果不确定自己是安装过，可以在终端输入pip进行检测。如果出现-bash: /usr/local/bin/pip: No such file or directory 提示说明，则尚未安装 Pip，需要进行第2-3步。

Ⅱ. 终端输入sudo easy_install pip，输入 mac 密码，进入安装：

Ⅲ. 最终显示Finished processing dependencies for pip，Pip 配置完成。可以通过pip --version 查看 Pip 版本。

Ⅳ. 终端运行pip install sphinx，完成安装。

Ⅴ. 完成安装后，可以检查 Sphinx 配置情况：

终端输入pip list，回车，正常情况下可以看到若干以 Sphinx 开头的包：

Homebrew 安装与配置

Homebrew 可以视为套件管理器。它是一款 Mac OS 平台下的软件包管理工具，拥有安装、卸载、更新、查看、搜索等很多实用的功能，不需要关注各种依赖和文件路径的情况。配置好 Homebrew 后，安装包、补充缺失的包比较比较便捷。

Ⅰ. Homebrew 依赖于 Xcode Command Line Tools，所以会自动先安装 Xcode Command Line Tools；如果有报错，也可以用命令手动安装：xcode-select --install。

Ⅱ. 前往 homebrew 官网，复制首页代码行到终端执行。

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

中间需要输入一次 mac 密码：

提示：-bash: brew: command not found 是一种常见报错，解决办法是在终端输入 sudo vim .bash_profile，添加 export PATH="/usr/local/bin:$PATH"；最后输入 source .bash_profile 使配置生效。

Ⅲ. 出现Installation successful!的提示即为 Homebrew 配置完成。

Ⅳ. 完成 Homebrew 配置后，终端输入brew install sphinx-doc，安装 Sphinx 。

Ⅴ. 完成安装后，可以检查 Sphinx 配置情况：

终端输入brew list，回车，正常情况下可以看到 Sphinx 的包：

---

Visual Studio Code 安装与配置

Ⅰ. 打开 Visual Studio Code 官网，下载适合的安装包，可以勾选全部复选框完成安装任务。

Ⅱ. 完成安装后打开 VS Code，在 Extentions 中安装 Python 和 reStructuredText 拓展。

VS Code 调用 Sphinx (Anaconda)

完成以上步骤后，已经基本搭建好了一个基于 Anaconda 和 VS Code 的一体化 Sphinx 工作台。在这一环节中，同学们可以检测自己的 Sphinx 开发环境， 为下一节 “第一个 Sphinx 项目” 做好准备。

Ⅰ. 在计算机任意位置新建一个文件夹，命名为 “learn-sphinx”，拖至 VS Code 打开。

文件夹会显示在左侧边栏，下一小节创建项目的文件将会储存在这个文件夹。

Ⅱ. 打开 VS Code 窗口的集成 Terminal（可使用 Ctrl + ` 快捷键唤出/隐藏），输入 sphinx-build --version 回车:

如果一切正常，同学们将会看到已安装 Sphinx 版本号（这里显示的版本是 |sphinx_version| ），这说明 Sphinx 开发环境已正确部署至计算机。