安装 Sphinx¶
概述¶
Sphinx 是用 Python 写的，支持 Python 3.6+。它建立在许多第三方库之上，如 Docutils 和 Jinja 。这些库在安装 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 安装，也可以作为 Python 发行版的一部分，如 Anaconda。
Homebrew¶
$ brew install sphinx-doc
更多信息，请参考 软件包概述 。
MacPorts¶
使用 port 安装 python3x-sphinx。
$ sudo port install py38-sphinx
要设置可执行路径，使用 port select 命令：
$ sudo port select --set python python38
$ sudo port select --set sphinx py38-sphinx
更多信息，请参考 软件包概述 。
Anaconda¶
$ conda install sphinx
Windows¶
Sphinx 可以用 Chocolatey 来安装，或者 手动安装。
Chocolatey¶
$ choco install sphinx
You would need to install Chocolatey before running this.
欲了解更多信息，请参考 chocolatey 页面。
其他方式¶
大多数 Windows 用户都没有默认安装 Python，所以我们先从安装 Python 本身开始。要检查你是否已经安装了 Python 安装，打开 命令提示符 （ ⊞Win-r 并输入 cmd）。一旦命令提示符打开，输入 python --version，然后按回车。如果 Python 已经安装，你会看到 Python 的版本被打印到屏幕上。如果你没有安装 Python，请参考 Hitchhikers Guide to Python 中的在 Windows 上的安装 Python。你必须安装 Python 3。
一旦 Python 安装完毕，你可以用 pip 安装 Sphinx。请参考 pip 安装说明 以获得更多信息。
从 PyPI 安装¶
Sphinx 软件包在 Python 软件包索引 上发布。安装 PyPI 软件包的首选工具 pip。这个工具在所有现代版本的Python中都有提供。
在 Linux 或 MacOS 上，你应该打开你的终端并运行以下命令。
$ pip install -U sphinx
在 Windows 中，你应该打开 命令提示符 （⊞Win-r 并输入 cmd）并运行相同的命令。
C:\> pip install -U sphinx
安装后，在命令提示符上输入 sphinx-build --version。提示符。如果一切正常，你会看到刚刚安装的 Sphinx 包的版本号。
从 PyPI 安装也允许你安装最新的开发版本。你一般不需要（或不想）这样做，但如果你在最新的稳定版中发现了一个可能的错误，它可能会很有用。要做到这一点，请使用 --pre 标志。
$ pip install -U --pre sphinx
使用虚拟环境¶
当使用 pip 安装 Sphinx 时。强烈建议使用 虚拟环境。它将安装的软件包与系统软件包隔离。因此不需要使用管理员的权限。要在 .venv 目录下创建一个虚拟环境。使用以下命令。
$ python -m venv .venv
你可以在 Python 打包用户指南 中阅读更多关于它们的信息。
警告
请注意，在某些Linux发行版中，如 Debian 和 Ubuntu。这可能需要一个额外的安装步骤，如下所示。
$ apt-get install python3-venv
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 文件。
从源码安装¶
你可以直接从 Git 仓库 的克隆中安装 Sphinx。这可以通过克隆仓库并从本地克隆中安装，也可以简单地通过 git 直接安装。
$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .
$ pip install git+https://github.com/sphinx-doc/sphinx