安裝 Sphinx¶

Sphinx 是一款 Python 應用程式。您可以透過以下任一方式進行安裝。

After installation, you can check that Sphinx is available by running

$ sphinx-build --version

This should print out the Sphinx version number.

小訣竅

For local development, it is generally recommended to install Sphinx into a non-global environment (using for example venv or conda environments). This will allow for the use of separate sphinx versions and third-party extensions for each sphinx project.

PyPI 軟體包¶

Sphinx packages are published on the Python Package Index (PyPI). The preferred tool for installing packages from PyPI is pip, which is included in all modern versions of Python.

執行以下命令：

$ pip install -U sphinx

小訣竅

To avoid issues when rebuilding your environment, it is advisable to pin sphinx and third-party extension versions in a requirements.txt file:

$ pip install -r requirements.txt

Or, if writing documentation for a Python package, place the dependencies in the pyproject.toml file:

$ pip install . --group docs

Conda 軟體包¶

To work with conda, you need a conda-based Python distribution such as anaconda, miniconda, miniforge or micromamba.

Sphinx is available both via the anaconda main channel (maintained by Anaconda Inc.)

$ conda install sphinx

as well as via the conda-forge community channel

$ conda install -c conda-forge sphinx

作業系統專用的軟體包管理器¶

您可以使用作業系統專用的軟體包管理器在系統中安裝全域版本的 Sphinx。但是，請注意這種方式的靈活性較低，若您需要在不同專案之間切換工作，可能會遇到相容性問題。

Linux¶

Debian/Ubuntu¶

Install either python3-sphinx using apt-get:

$ apt-get install python3-sphinx

If it not already present, this will install Python for you.

RHEL, CentOS¶

使用 yum 安裝 python-sphinx：

$ yum install python-sphinx

If it not already present, this will install Python for you.

其他散布版：¶

Most Linux distributions have Sphinx in their package repositories. Usually the package is called python3-sphinx, python-sphinx or sphinx. Be aware that there are at least two other packages with sphinx in their name: a speech recognition toolkit (CMU Sphinx) and a full-text search database (Sphinx search).

macOS¶

Sphinx 可以使用 Homebrew 或 MacPorts 進行安裝。

Homebrew¶

$ brew install sphinx-doc

For more information, refer to the package overview.

MacPorts¶

使用 port 安裝 python3x-sphinx：

$ sudo port install py314-sphinx

To set up the executable paths, use the port select command:

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

For more information, refer to the package overview.

Windows¶

Sphinx 可以使用 Chocolatey 進行安裝。

Chocolatey¶

$ choco install sphinx

You would need to install Chocolatey before running this.

For more information, refer to the chocolatey page.

Docker¶

Docker images for Sphinx are published on the Docker Hub. There are two kind of images:

Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX. Please choose one for your purpose.

備註

sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large (over 2GB!).

提示

When using docker images, please use docker run command to invoke sphinx commands. For example, you can use following command to create a Sphinx project:

$ 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

For more details, please read README file of docker images.

安裝最新的開發發行版¶

You can install the latest development from PyPI using the --pre flag:

$ pip install -U --pre sphinx

警告

You will not generally need (or want) to do this, but it can be useful if you see a possible bug in the latest stable release.

從來源碼安裝¶

You can install Sphinx directly from a clone of the Git repository. This can be done either by cloning the repo and installing from the local clone, on simply installing directly via git.

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

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

You can also download a snapshot of the Git repo in either tar.gz or zip format. Once downloaded and extracted, these can be installed with pip as above.