Sphinxのインストール¶
Sphinx is a Python application. It can be installed in one of the ways described below.
After installation, you can check that Sphinx is available by running
$ sphinx-build --version
This should print out the Sphinx version number.
Tip
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 package¶
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.
Run the following command:
$ pip install -U sphinx
Tip
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 .[docs]
Conda package¶
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
OS-specific package manager¶
You may install a global version of Sphinx into your system using OS-specific package managers. However, be aware that this is less flexible and you may run into compatibility issues if you want to work across different projects.
Linux¶
Debian/Ubuntu¶
apt-get: コマンドで python3-sphinx
をインストールしてください。
$ apt-get install python3-sphinx
もしPythonがインストールされていなくても、このコマンドで一緒にインストールされます。
RHEL, CentOS¶
yum コマンドで python-sphinx
をインストールしてください:
$ yum install python-sphinx
もしPythonがインストールされていなくても、このコマンドで一緒にインストールされます。
他のディストリビューション¶
ほとんどのLinuxディストリビューションは、OSのパッケージ管理リポジトリにSphinxが用意されています。一般的なパッケージ名は python3-sphinx
, python-sphinx
, sphinx
のいずれかです。 sphinx
という名前をもつ別の用途のパッケージが他に2つあることに注意してください: 音声認識ツールキット(CMU Sphinx), フルテキスト検索データベース(Sphinx search)。
macOS¶
Sphinx can be installed using Homebrew, MacPorts.
Homebrew¶
$ brew install sphinx-doc
詳しくは、 package overview を参照してください。
MacPorts¶
port: コマンドで python3x-sphinx
をインストールしてください。
$ sudo port install py313-sphinx
実行パスを設定するために port select
コマンドを使って下さい:
$ sudo port select --set python python313
$ sudo port select --set sphinx py313-sphinx
詳しくは、 package overview を参照してください。
Windows¶
Sphinx can be install using 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 にはTeXLiveパッケージが含まれています。そのため、イメージは非常に大きくなります(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
詳細については、docker imagesの README file をお読みください。
Installation of the latest development release¶
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.
ソースからインストール¶
Git repository のクローンから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 を使用してインストールできます。