安装 Sphinx¶
Sphinx 是一个 Python 应用程序。它可以通过以下几种方式之一安装。
安装完成后，您可以通过运行以下命令来检查 Sphinx 是否可用：
$ sphinx-build --version
这将打印出 Sphinx 版本号。
PyPI 包¶
Sphinx 包发布在 Python Package Index (PyPI) 上。从 PyPI 安装包的首选工具是 pip，它包含在所有现代版本的 Python 中。
运行以下命令：
$ pip install -U sphinx
提示
为了避免在重建环境时出现问题，建议在 requirements.txt 文件 中固定 sphinx 和第三方扩展版本。
$ pip install -r requirements.txt
或者，如果正在为 Python 包编写文档，请将依赖项放在 pyproject.toml 文件 中。
$ pip install .[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 尚未存在，这将为您安装 Python。
RHEL, CentOS¶
使用 yum 安装 python-sphinx
$ yum install python-sphinx
如果 Python 尚未存在，这将为您安装 Python。
其他发行版¶
大多数 Linux 发行版在其软件包存储库中都有 Sphinx。通常，软件包名为 python3-sphinx、python-sphinx 或 sphinx。请注意，至少还有两个其他软件包在其名称中包含 sphinx：一个语音识别工具包（CMU Sphinx）和一个全文搜索数据库（Sphinx search）。
macOS¶
Sphinx 可以使用 Homebrew、MacPorts 安装。
Homebrew¶
$ brew install sphinx-doc
有关更多信息，请参阅 软件包概述。
MacPorts¶
使用 port 安装 python3x-sphinx
$ sudo port install py312-sphinx
要设置可执行文件路径，请使用 port select 命令
$ sudo port select --set python python312
$ sudo port select --set sphinx py312-sphinx
有关更多信息，请参阅 软件包概述。
Windows¶
Sphinx 可以使用 Chocolatey 安装。
Chocolatey¶
$ choco install sphinx
您需要先 安装 Chocolatey，然后才能运行此命令。
有关更多信息，请参阅 chocolatey 页面。
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 文件。
安装最新开发版本¶
您可以使用 --pre 标志从 PyPI 安装最新的开发版本
$ pip install -U --pre sphinx
警告
您通常不需要（也不希望）这样做，但如果您在最新的稳定版本中发现可能的错误，这可能会有用。
从源代码安装¶
您可以直接从 Git 存储库 的克隆中安装 Sphinx。这可以通过克隆存储库并从本地克隆中安装来完成，也可以通过 git 直接安装。
$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .
$ pip install git+https://github.com/sphinx-doc/sphinx
您还可以下载 Git 存储库的快照，格式为 tar.gz 或 zip。下载并解压缩后，可以使用上述 pip 安装这些文件。