安装 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.
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
有关更多信息,请参阅 包概述 .
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