Installing Sphinx¶
Overview¶
Sphinx is written in Python and supports both Python 2.7 and Python 3.3+. We recommend the latter.
Linux¶
Debian/Ubuntu¶
Install either python3-sphinx
(Python 3) or python-sphinx
(Python 2)
using apt-get:
$ apt-get install python3-sphinx
If it not already present, this will install Python for you.
RHEL, CentOS¶
Install python-sphinx
using yum:
$ yum install python-sphinx
If it not already present, this will install Python for you.
Other distributions¶
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 can be installed using Homebrew, MacPorts, or as part of a Python distribution such as Anaconda.
MacPorts¶
Install either python36-sphinx
(Python 3) or python27-sphinx
(Python 2)
using port:
$ sudo port install py36-sphinx
To set up the executable paths, use the port select
command:
$ sudo port select --set python python36
$ sudo port select --set sphinx py36-sphinx
For more information, refer to the package overview.
Anaconda¶
$ conda install sphinx
Windows¶
Todo
Could we start packaging this?
Most Windows users do not have Python installed by default, so we begin with the installation of Python itself. If you are unsure, open the Command Prompt (⊞Win-r and type cmd). Once the command prompt is open, type python --version and press Enter. If Python is available, you will see the version of Python printed to the screen. If you do not have Python installed, refer to the Hitchhikers Guide to Python’s Python on Windows installation guides. You can install either Python 3 or Python 2.7. Python 3 is recommended.
Once Python is installed, you can install Sphinx using pip. Refer to the pip installation instructions below for more information.
Installation from PyPI¶
Sphinx packages are published on the Python Package Index. The preferred tool for installing packages from PyPI is pip. This tool is provided with all modern versions of Python.
On Linux or MacOS, you should open your terminal and run the following command.
$ pip install -U sphinx
On Windows, you should open Command Prompt (⊞Win-r and type cmd) and run the same command.
C:\> pip install -U sphinx
After installation, type sphinx-build --version on the command prompt. If everything worked fine, you will see the version number for the Sphinx package you just installed.
Installation from PyPI also allows you to install the latest development
release. 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. To do this, use
the --pre
flag.
$ pip install -U --pre sphinx
Installation from source¶
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.