diff --git a/doc/contents.rst b/doc/contents.rst index ab8d09eb0..772145f26 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -7,6 +7,8 @@ Sphinx documentation contents .. toctree:: :maxdepth: 2 + usage/installation + intro tutorial man/index diff --git a/doc/install.rst b/doc/install.rst deleted file mode 100644 index bd2f18ad3..000000000 --- a/doc/install.rst +++ /dev/null @@ -1,122 +0,0 @@ -:orphan: - -Installing Sphinx -================= - -Since Sphinx is written in the Python language, you need to install Python -(the required version is at least 2.7) and Sphinx. - -Sphinx packages are available on the `Python Package Index -`_. - -You can also download a snapshot from the Git repository: - -* as a `.tar.gz `__ - file or -* as a `.zip `_ file - -There are introductions for several environments: - -.. contents:: - :depth: 1 - :local: - :backlinks: none - - -Debian/Ubuntu: Install Sphinx using packaging system ----------------------------------------------------- - -You may install using this command if you use Debian/Ubuntu. - -.. code-block:: bash - - $ apt-get install python-sphinx - - -Other Linux distributions -------------------------- - -Most Linux distributions have Sphinx in their package repositories. Usually the -package is called "python-sphinx", "python-Sphinx" or "sphinx". Be aware that -there are two other packages with "sphinx" in their name: a speech recognition -toolkit (CMU Sphinx) and a full-text search database (Sphinx search). - - -Mac OS X: Install Sphinx using MacPorts ---------------------------------------- - -If you use Mac OS X `MacPorts `_, use this command to -install all necessary software. - -.. code-block:: bash - - $ sudo port install py27-sphinx - -To set up the executable paths, use the ``port select`` command: - -.. code-block:: bash - - $ sudo port select --set python python27 - $ sudo port select --set sphinx py27-sphinx - -Type :command:`which sphinx-quickstart` to check if the installation was -successful. - - -Windows: Install Python and Sphinx ----------------------------------- - -Install Python -^^^^^^^^^^^^^^ - -Most Windows users do not have Python, so we begin with the -installation of Python itself. If you have already installed -Python, please skip to the next section. - -.. note:: - - Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.6 can run - under Python 2.7, 3.4, 3.5, 3.6, with the recommended version being 2.7. This - chapter assumes you are installing Python 2.7. - -Go to https://www.python.org/, the main download site for Python. -Hover over the "Downloads" menu and select a Python version to download. - -.. image:: pythonorg.png - -Follow the Windows installer for Python. When you reach the screen that -lets you customize the installation, scroll to the bottom of the list -and change "Add python.exe to Path" so that it will be installed. - -.. image:: installpython.png - -Now run the **Command Prompt**. After the command prompt window appears, type -``python`` and Enter. If the Python installation was successful, the -installed Python version is printed, and you are greeted by the prompt -``>>>``: - -.. code-block:: text - - C:\>python - Python 2.7.14 (v2.7.14:84471935ed, Sep 16 2017, 20:19:30) [MSC v.1500 32 bit (Intel)] on win32 - Type "help", "copyright", "credits" or "license" for more information. - >>> - -Type ``Ctrl+Z`` and ``Enter`` to quit. - - -Install Sphinx using pip -^^^^^^^^^^^^^^^^^^^^^^^^ - -Type this line in the command prompt: - -.. code-block:: text - - C:\>pip install sphinx - -After installation, type :command:`sphinx-build -h` on the command prompt. If -everything worked fine, you will get a Sphinx version number and a list of -options for this command. - -That it. Installation is over. Head to :doc:`tutorial` to make a Sphinx -project. diff --git a/doc/installpython.png b/doc/installpython.png deleted file mode 100644 index 8931737fc..000000000 Binary files a/doc/installpython.png and /dev/null differ diff --git a/doc/pythonorg.png b/doc/pythonorg.png deleted file mode 100644 index 381073c97..000000000 Binary files a/doc/pythonorg.png and /dev/null differ diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst new file mode 100644 index 000000000..7ccdd677f --- /dev/null +++ b/doc/usage/installation.rst @@ -0,0 +1,179 @@ +================= +Installing Sphinx +================= + +.. contents:: + :depth: 1 + :local: + :backlinks: none + +Overview +-------- + +Sphinx is written in `Python`__ and supports both Python 2.7 and Python 3.3+. +We recommend the latter. + +__ http://docs.python-guide.org/en/latest/ + + +Linux +----- + +Debian/Ubuntu +~~~~~~~~~~~~~ + +Install either ``python3-sphinx`` (Python 3) or ``python-sphinx`` (Python 2) +using :command:`apt-get`: + +.. code-block:: bash + + $ apt-get install python3-sphinx + +If it not already present, this will install Python for you. + +RHEL, CentOS +~~~~~~~~~~~~ + +Install ``python-sphinx`` using :command:`yum`: + +.. code-block:: bash + + $ 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`__ or `MacPorts`__. + +__ https://brew.sh/ +__ https://www.macports.org/ + +Homebrew +~~~~~~~~ + +.. code-block:: bash + + $ brew install sphinx-doc + +For more information, refer to the `package overview`__. + +__ http://formulae.brew.sh/formula/sphinx-doc + +MacPorts +~~~~~~~~ + +Install either ``python36-sphinx`` (Python 3) or ``python27-sphinx`` (Python 2) +using :command:`port`: + +.. code-block:: bash + + $ sudo port install py36-sphinx + +To set up the executable paths, use the ``port select`` command: + +.. code-block:: bash + + $ sudo port select --set python python36 + $ sudo port select --set sphinx py36-sphinx + +For more information, refer to the `package overview`__. + +__ https://www.macports.org/ports.php?by=library&substr=py36-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* (:kbd:`Control-r` and type :command:`cmd`). Once the command prompt is +open, type :command:`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 :command:`pip`. Refer +to the :ref:`pip installation instructions ` below for more +information. + +__ http://docs.python-guide.org/en/latest/ +__ http://docs.python-guide.org/en/latest/starting/install3/win/ +__ http://docs.python-guide.org/en/latest/starting/install/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. + +.. code-block:: shell + + $ pip install -U sphinx + +On Windows, you should open *Command Prompt* (:kbd:`Control-r` and type +:command:`cmd`) and run the same command. + +.. code-block:: bat + + 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. + +.. code-block:: shell + + $ 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 :command:`git`. + +.. code-block:: shell + + $ git clone https://github.com/sphinx-doc/sphinx + $ cd sphinx + $ pip install . + +.. code-block:: shell + + $ 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 +:command:`pip` as above. + +__ https://github.com/sphinx-doc/sphinx +__ https://github.com/sphinx-doc/sphinx/archive/master.tar.gz +__ https://github.com/sphinx-doc/sphinx/archive/master.zip