mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
DOC: Rewrite installation instructions (#12458)
- Put pip and conda as the most common options first - Don't distinguish Linux / Windows in the pip commands. - Replace the venv instructions by a general tip to use environments and link out for details. - Collect all OS-specific package manager in one section - Remove the "Windows - Other methods" secion. - Move latest development release to a separate entry. Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
This commit is contained in:
Tim Hoffmann
GitHub
parent
b70578f80c
commit
a53a758d40
@ -2,30 +2,101 @@
|
||||
Installing Sphinx
|
||||
=================
|
||||
|
||||
.. contents::
|
||||
:depth: 1
|
||||
Sphinx is a Python application. It can be installed in one of the ways described
|
||||
below.
|
||||
|
||||
.. contents:: Installation methods
|
||||
:depth: 2
|
||||
:local:
|
||||
:backlinks: none
|
||||
|
||||
.. highlight:: console
|
||||
|
||||
Overview
|
||||
--------
|
||||
After installation, you can check that Sphinx is available by running ::
|
||||
|
||||
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.
|
||||
$ sphinx-build --version
|
||||
|
||||
__ https://docs.python-guide.org/
|
||||
__ https://docutils.sourceforge.io/
|
||||
__ https://jinja.palletsprojects.com/
|
||||
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.
|
||||
|
||||
__ https://docs.python.org/3/library/venv.html
|
||||
__ https://conda.io/projects/conda/en/latest/user-guide/getting-started.html
|
||||
|
||||
|
||||
.. _install-pypi:
|
||||
|
||||
PyPI package
|
||||
------------
|
||||
|
||||
Sphinx packages are published on the `Python Package Index
|
||||
<https://pypi.org/project/Sphinx/>`_ (PyPI). The preferred tool for installing
|
||||
packages from PyPI is :command:`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]
|
||||
|
||||
__ https://pip.pypa.io/en/stable/reference/requirements-file-format/
|
||||
__ https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#dependencies-optional-dependencies
|
||||
|
||||
.. _install-conda:
|
||||
|
||||
Conda package
|
||||
-------------
|
||||
To work with :command:`conda`, you need a conda-based Python distribution such as
|
||||
`anaconda`__, `miniconda`__, `miniforge`__ or `micromamba`__.
|
||||
|
||||
__ https://docs.anaconda.com/anaconda/
|
||||
__ https://docs.anaconda.com/miniconda/
|
||||
__ https://github.com/conda-forge/miniforge/
|
||||
__ https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html
|
||||
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~
|
||||
"""""""""""""
|
||||
|
||||
Install either ``python3-sphinx`` using :command:`apt-get`:
|
||||
|
||||
@ -36,7 +107,7 @@ Install either ``python3-sphinx`` using :command:`apt-get`:
|
||||
If it not already present, this will install Python for you.
|
||||
|
||||
RHEL, CentOS
|
||||
~~~~~~~~~~~~
|
||||
""""""""""""
|
||||
|
||||
Install ``python-sphinx`` using :command:`yum`:
|
||||
|
||||
@ -47,7 +118,7 @@ Install ``python-sphinx`` using :command:`yum`:
|
||||
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
|
||||
@ -55,19 +126,16 @@ 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`__.
|
||||
Sphinx can be installed using `Homebrew`__, `MacPorts`__.
|
||||
|
||||
__ https://brew.sh/
|
||||
__ https://www.macports.org/
|
||||
__ https://www.anaconda.com/download
|
||||
|
||||
Homebrew
|
||||
~~~~~~~~
|
||||
""""""""
|
||||
|
||||
::
|
||||
|
||||
@ -78,7 +146,7 @@ For more information, refer to the `package overview`__.
|
||||
__ https://formulae.brew.sh/formula/sphinx-doc
|
||||
|
||||
MacPorts
|
||||
~~~~~~~~
|
||||
""""""""
|
||||
|
||||
Install either ``python3x-sphinx`` using :command:`port`:
|
||||
|
||||
@ -97,23 +165,15 @@ For more information, refer to the `package overview`__.
|
||||
|
||||
__ https://www.macports.org/ports.php?by=library&substr=py39-sphinx
|
||||
|
||||
Anaconda
|
||||
~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
$ conda install sphinx
|
||||
|
||||
Windows
|
||||
-------
|
||||
~~~~~~~
|
||||
|
||||
Sphinx can be install using `Chocolatey`__ or
|
||||
:ref:`installed manually <windows-other-method>`.
|
||||
Sphinx can be install using `Chocolatey`__.
|
||||
|
||||
__ https://chocolatey.org/
|
||||
|
||||
Chocolatey
|
||||
~~~~~~~~~~
|
||||
""""""""""
|
||||
|
||||
::
|
||||
|
||||
@ -127,89 +187,6 @@ For more information, refer to the `chocolatey page`__.
|
||||
|
||||
__ https://chocolatey.org/packages/sphinx/
|
||||
|
||||
.. _windows-other-method:
|
||||
|
||||
Other Methods
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Most Windows users do not have Python installed by default, so we begin with
|
||||
the installation of Python itself. To check if you already have Python
|
||||
installed, open the *Command Prompt* (:kbd:`⊞Win-r` and type :command:`cmd`).
|
||||
Once the command prompt is open, type :command:`python --version` and press
|
||||
Enter. If Python is installed, 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 must install
|
||||
`Python 3`__.
|
||||
|
||||
Once Python is installed, you can install Sphinx using :command:`pip`. Refer
|
||||
to the :ref:`pip installation instructions <install-pypi>` below for more
|
||||
information.
|
||||
|
||||
__ https://docs.python-guide.org/
|
||||
__ https://docs.python-guide.org/starting/install3/win/
|
||||
|
||||
|
||||
.. _install-pypi:
|
||||
|
||||
Installation from PyPI
|
||||
----------------------
|
||||
|
||||
Sphinx packages are published on the `Python Package Index
|
||||
<https://pypi.org/project/Sphinx/>`_. The preferred tool for installing
|
||||
packages from *PyPI* is :command:`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* (:kbd:`⊞Win-r` and type
|
||||
:command:`cmd`) and run the same command.
|
||||
|
||||
.. code-block:: doscon
|
||||
|
||||
C:\> pip install -U sphinx
|
||||
|
||||
After installation, type :command:`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
|
||||
|
||||
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
|
||||
|
||||
.. seealso:: :mod:`venv` -- creating virtual environments
|
||||
|
||||
.. warning::
|
||||
|
||||
Note that in some Linux distributions, such as Debian and Ubuntu,
|
||||
this might require an extra installation step as follows.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ apt-get install python3-venv
|
||||
|
||||
Docker
|
||||
------
|
||||
|
||||
@ -251,6 +228,17 @@ For more details, please read `README file`__ of docker images.
|
||||
|
||||
.. __: https://hub.docker.com/r/sphinxdoc/sphinx
|
||||
|
||||
Installation of the latest development release
|
||||
----------------------------------------------
|
||||
|
||||
You can install the latest development from *PyPI* using the ``--pre`` flag::
|
||||
|
||||
$ pip install -U --pre sphinx
|
||||
|
||||
.. warning::
|
||||
|
||||
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.
|
||||
|
||||
Installation from source
|
||||
------------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user