From bb98bb85e13364aadbd77f9477921ef17764e680 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 21 Jun 2024 23:10:02 +0200 Subject: [PATCH] DOC: Rewrite installation instructions --- doc/usage/installation.rst | 214 ++++++++++++++++++------------------- 1 file changed, 105 insertions(+), 109 deletions(-) diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst index 13dc6a983c0..2baa9245b3b 100644 --- a/doc/usage/installation.rst +++ b/doc/usage/installation.rst @@ -9,23 +9,110 @@ Installing Sphinx .. highlight:: console -Overview --------- +Sphinx is a Python application. -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. +.. note:: + + If you use Sphinx for documenting a Python library or application, it is + generally recommended to install Sphinx into your dev environment. + By adding Sphinx and 3rdparty extensions or themes that you use to your dev + dependencies, you make sure that you have a consistent setup for building + your documentation. + +.. _install-pypi: + +PyPI packages +------------- + +Sphinx packages are published on the `Python Package Index +`_. The preferred tool for installing +packages from *PyPI* is :command:`pip`, which is included in 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. + +.. note:: + + 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 + +.. _install-conda: + +Conda packages +-------------- +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 :: -__ https://docs.python-guide.org/ -__ https://docutils.sourceforge.io/ -__ https://jinja.palletsprojects.com/ + $ conda install -c conda-forge sphinx +OS-specific package managers +---------------------------- + +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 +123,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 +134,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 @@ -57,17 +144,15 @@ a speech recognition toolkit (*CMU Sphinx*) and a full-text search database 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 +163,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,15 +182,8 @@ 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 `. @@ -113,7 +191,7 @@ Sphinx can be install using `Chocolatey`__ or __ https://chocolatey.org/ Chocolatey -~~~~~~~~~~ +"""""""""" :: @@ -127,88 +205,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 ` 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 -`_. 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 ------