安装Sphinx

概述

Sphinx is written in Python and supports Python 3.9+. It builds upon the shoulders of many third-party libraries such as Docutils and Jinja, which are installed when Sphinx is installed.

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

更多信息请参阅 package overview 。

MacPorts

使用 port 安装 python3x-sphinx ：

$ sudo port install py39-sphinx

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

$ sudo port select --set python python39
$ sudo port select --set sphinx py39-sphinx

更多信息请参阅 package overview 。

Anaconda

$ conda install sphinx

Windows

Sphinx 可以通过 Chocolatey 安装，也可以 自己手动安装 。

Chocolatey

$ choco install sphinx

You would need to install Chocolatey before running this.

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

其他方法

大多数 Windows 用户并没有安装 Python，因此我们首先安装 Python 本身。 如果您不确定自己是否安装了 Python，请打开 命令提示符 (⊞Win-r 并输入 cmd) 。打开命令提示符后，键入 python --version 并按 Enter 键。 如果安装了 Python，您将看到在屏幕上输出的 Python 版本。 如果没有安装 Python，请参阅 Windows 安装指南中的 Hitchhikers Guide to Python’s 。 必须安装 Python 3 。

安装 Python 后，您可以使用 pip 安装 Sphinx 。更多信息请参阅下面的 pip installation instructions 。

从PyPI安装

Sphinx 包发布在 Python Package Index 上。 从 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

Using virtual environments

When installing Sphinx using pip, it is highly recommended to use virtual environments, which isolate the installed packages from the system packages, thus removing the need to use administrator privileges. To create a virtual environment in the .venv directory, use the following command.

$ python -m venv .venv

参见

venv – creating virtual environments

警告

Note that in some Linux distributions, such as Debian and Ubuntu, this might require an extra installation step as follows.

$ apt-get install python3-venv

Docker

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

• sphinxdoc/sphinx

• sphinxdoc/sphinx-latexpdf

前一种是用于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

And you can use the following command to build HTML document:

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

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

从源代码安装

您可以直接从 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 命令安装。