安装Sphinx¶

作为一款 Python 程序，Sphinx 可以通过以下任意方式进行安装。

安装完成后，您可以通过运行以下命令来检查 Sphinx 是否已成功安装

$ sphinx-build --version

这将会在终端输出 Sphinx 的版本号。

小技巧

在本地进行开发，通常建议将 Sphinx 安装在非全局环境中（例如使用 venv 或 conda 环境）。这将允许每个 Sphinx 项目使用独立的 Sphinx 版本和第三方扩展。

PyPI 包¶

Sphinx 软件包发布在 Python 软件包索引 (PyPI) 上。从 PyPI 安装软件包的首选工具是 pip ，它包含在所有现代版本的 Python 中。

运行以下命令:

$ pip install -U sphinx

小技巧

为了避免在重建环境时出现问题，建议在 requirements.txt file 中固定 Sphinx 和第三方扩展的版本:

$ pip install -r requirements.txt

或者，如果您正在为 Python 包编写文档，请将依赖项放在 pyproject.toml file 中:

$ pip install . --group docs

Conda 包¶

要使用 conda ，您需要一个基于 conda 的 Python 发行版，例如 anaconda ， miniconda ， miniforge 或 micromamba 。

Sphinx 可通过 anaconda main 频道（由 Anaconda Inc. 维护）获得，

$ conda install sphinx

也可通过 conda-forge 社区频道获得

$ conda install -c conda-forge sphinx

特定操作系统的软件包管理器¶

您可以使用特定操作系统的软件包管理器将 Sphinx 的全局版本安装到系统中。但是，请注意，这种方法的灵活性较差，如果您想在不同项目之间工作，可能会遇到兼容性问题。

Linux¶

Debian/Ubuntu¶

使用 apt-get 安装 python3-sphinx ：

$ apt-get install python3-sphinx

如果Python不存在，它将会被安装。

RHEL, CentOS¶

使用 yum 安装 python-sphinx :

$ yum install python-sphinx

如果Python不存在，它将会被安装。

其他发行版¶

大多数 Linux 发行版的软件包存储库中都有 Sphinx。通常这个包被称为 python3-sphinx ， python-sphinx 或 sphinx 。请注意，还有至少两个软件包其名称中带有 sphinx 的：语音识别工具包（CMU Sphinx）和全文搜索数据库（Sphinx search）。

macOS¶

Sphinx 可以使用 Homebrew ， MacPorts 安装。

Homebrew¶

$ brew install sphinx-doc

更多信息请参阅 package overview 。

MacPorts¶

使用 port 安装 python3x-sphinx ：

$ sudo port install py314-sphinx

使用 port select 命令设置可执行路径：

$ sudo port select --set python python314
$ sudo port select --set sphinx py314-sphinx

更多信息请参阅 package overview 。

Windows¶

Sphinx 可以使用 Chocolatey 安装。

Chocolatey¶

$ choco install sphinx

在运行此命令之前，您需要先安装 Chocolatey 。

有关更多消息，请参考 chocolatey page 。

Docker¶

Sphinx 的 Docker 镜像发布在 Docker Hub 上。有两种镜像可选：

前一种是用于Sphinx的常规使用，后一种主要用于使用LaTeX的PDF构建。请根据您的目的选择一个。

备注

sphinxdoc/sphinx-latexpdf 包含TeXLive 软件包。因此，镜像非常大（超过2GB！）。

提示

使用 docker 镜像时，请使用 docker run 命令调用 sphinx 命令。例如，用以下命令创建一个 Sphinx 项目:

$ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart

您可以使用以下命令来构建 HTML 文档：

$ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html

有关更多详细信息，请阅读 Docker 镜像的 README file 。

安装最新的开发版本¶

您可以使用 --pre 标志从 PyPI 安装最新的开发版本:

$ pip install -U --pre sphinx

警告

通常情况下，您不需要（也不想）这样做，但如果您在最新的稳定版本中发现了一个可能的错误，这会很有用。

从源代码安装¶

您可以直接从 Git 仓库下载并安装 Sphinx 。这可以通过 git 命令克隆 repo 并在本地直接安装即可完成。

$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .

$ pip install git+https://github.com/sphinx-doc/sphinx

您也可以用 tar.gz 或 zip 格式下载 Git repo 的快照。下载并解压缩后，可以使用上述的 pip 命令安装。