mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
docs: proofread installation document
This commit is contained in:
Georg Brandl
parent
519be8ed6e
commit
d492aad352
156
doc/install.rst
156
doc/install.rst
@ -1,11 +1,12 @@
|
|||||||
:orphan:
|
:orphan:
|
||||||
|
|
||||||
Installing Sphinx
|
Installing Sphinx
|
||||||
==================
|
=================
|
||||||
|
|
||||||
Sphinx is written by Python, you need to install Python and Sphinx.
|
Since Sphinx is written in the Python language, you need to install Python
|
||||||
|
(the required version is at least 2.5) and Sphinx.
|
||||||
|
|
||||||
Sphinx package is available as a package on the `Python Package Index
|
Sphinx packages are available on the `Python Package Index
|
||||||
<http://pypi.python.org/pypi/Sphinx>`_.
|
<http://pypi.python.org/pypi/Sphinx>`_.
|
||||||
|
|
||||||
You can also download a snapshot from the Mercurial development repository:
|
You can also download a snapshot from the Mercurial development repository:
|
||||||
@ -14,7 +15,7 @@ You can also download a snapshot from the Mercurial development repository:
|
|||||||
file or
|
file or
|
||||||
* as a `.zip <https://bitbucket.org/birkenfeld/sphinx/get/default.zip>`_ file
|
* as a `.zip <https://bitbucket.org/birkenfeld/sphinx/get/default.zip>`_ file
|
||||||
|
|
||||||
There is introductions for each environments:
|
There are introductions for several environments:
|
||||||
|
|
||||||
.. contents::
|
.. contents::
|
||||||
:depth: 1
|
:depth: 1
|
||||||
@ -22,145 +23,128 @@ There is introductions for each environments:
|
|||||||
:backlinks: none
|
:backlinks: none
|
||||||
|
|
||||||
|
|
||||||
Install by your own
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
If you use system installed Python or build your own Python, you can
|
|
||||||
use that python to install Sphinx. The actual command list is same as
|
|
||||||
these install.
|
|
||||||
|
|
||||||
* `Install easy_install command`_
|
|
||||||
* `Install Sphinx`_
|
|
||||||
|
|
||||||
|
|
||||||
Debian/Ubuntu: Install Sphinx using packaging system
|
Debian/Ubuntu: Install Sphinx using packaging system
|
||||||
-----------------------------------------------------
|
----------------------------------------------------
|
||||||
|
|
||||||
You may install using this command if you use Debian/Ubuntu.
|
You may install using this command if you use Debian/Ubuntu.
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
$ aptitude install python-sphinx
|
$ 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
|
Mac OS X: Install Sphinx using MacPorts
|
||||||
----------------------------------------
|
---------------------------------------
|
||||||
|
|
||||||
If you use Mac OS X `MacPorts <http://www.macports.org/>`_ , use this
|
If you use Mac OS X `MacPorts <http://www.macports.org/>`_, use this command to
|
||||||
command to install all software.
|
install all necessary software.
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
$ sudo port install py27-sphinx
|
$ sudo port install py27-sphinx
|
||||||
|
|
||||||
However, the execution path is not added, use select command to use
|
To set up the executable paths, use the ``port select`` command:
|
||||||
Python2.7 as default.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
$ sudo port select --set python python27
|
$ sudo port select --set python python27
|
||||||
$ sudo port select --set sphinx py27-sphinx
|
$ sudo port select --set sphinx py27-sphinx
|
||||||
|
|
||||||
Type :command:`which sphinx-quickstart` to check the installation.
|
Type :command:`which sphinx-quickstart` to check if the installation was
|
||||||
|
successful.
|
||||||
|
|
||||||
|
|
||||||
Windows: Install Python and Sphinx
|
Windows: Install Python and Sphinx
|
||||||
-----------------------------------
|
----------------------------------
|
||||||
|
|
||||||
Intall Python
|
Install Python
|
||||||
^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Almost every Windows user do not have Python, we begin Python
|
Most Windows users do not have Python, so we begin with the installation of
|
||||||
installation. If you already install python, please skip this section.
|
Python itself. If you have already installed Python, please skip this section.
|
||||||
|
|
||||||
Go to http://python.org . This site is a headquarter of the
|
Go to http://python.org, the main download site for Python. Look at the left
|
||||||
Python. Look at Left sidebar and "Quick Links", Click "Windows
|
sidebar and under "Quick Links", click "Windows Installer" to download.
|
||||||
Installer" to download.
|
|
||||||
|
|
||||||
.. image:: pythonorg.png
|
.. image:: pythonorg.png
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
Currently, Python has two version, 2.X and 3.X. Sphinx-1.2 can
|
Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.2 can run
|
||||||
run under Python-2.5, 2.6, 2.7, 3.1, 3.2, 3.3.
|
under Python 2.5 to 2.7 and 3.1 to 3.3, with the recommended version being
|
||||||
You may get some advice from ML or other places.
|
2.7. This chapter assumes you have installed Python 2.7.
|
||||||
|
|
||||||
This chapter assumes Python-2.7.
|
Follow the Windows installer for Python.
|
||||||
|
|
||||||
|
|
||||||
Follow the normal Windows installer, the Python install will be completed.
|
|
||||||
|
|
||||||
.. image:: installpython.jpg
|
.. image:: installpython.jpg
|
||||||
|
|
||||||
After installation, you have better to add PATH to the Environment
|
After installation, you better add the Python executable directories to the
|
||||||
Variable in order to run Python from Command Prompt.
|
environment variable ``PATH`` in order to run Python and package commands such
|
||||||
|
as ``sphinx-build`` easily from the Command Prompt.
|
||||||
|
|
||||||
* Right-Click the My Computer Icon and open Property Dialog
|
* Right-click the "My Computer" icon and choose "Properties"
|
||||||
* Click Environment Variable button under detail tab
|
* Click the "Environment Variables" button under the "Advanced" tab
|
||||||
* Edit and add the path to the system variables PATH
|
|
||||||
|
|
||||||
Add these variables. This is for Python-2.7. If you use another version
|
* If "Path" (or "PATH") is already an entry in the "System variables" list, edit
|
||||||
of Python, change the "27" number. Add these pathes separeted by ";".
|
it. If it is not present, add a new variable called "PATH".
|
||||||
|
|
||||||
.. list-table:: Adding PATH
|
* Add these paths, separating entries by ";":
|
||||||
:widths: 10 40
|
|
||||||
:header-rows: 1
|
|
||||||
|
|
||||||
* - PATH
|
- ``C:\Python27`` -- this folder contains the main Python executable
|
||||||
- description
|
- ``C:\Python27\Scripts`` -- this folder will contain executables added by
|
||||||
* - C:\\Python27
|
Python packages installed with easy_install (see below)
|
||||||
- Folder which includes Python Command
|
|
||||||
* - C:\\Python27\\Scripts
|
|
||||||
- Folder which includes easy_install (described later) or sphinx commands
|
|
||||||
|
|
||||||
Run **Command Prompt** or enter ``cmd`` to the "search program and
|
This is for Python 2.7. If you use another version of
|
||||||
files" text box. After command prompt window appear, type
|
Python or installed to a non-default location, change the digits "27"
|
||||||
``python[Enter]``. If you can get installed python version and prompt
|
accordingly.
|
||||||
about ``>>>``, the Python installation is succeeded. Enter ``Ctrl+Z``
|
|
||||||
key to quit.
|
* Now run the **Command Prompt**. After command prompt window appear, type
|
||||||
|
``python`` and Enter. If the Python installation was successful, the
|
||||||
|
installed Python version is printed, and you are greeted by the prompt
|
||||||
|
``>>>``. Type ``Ctrl+Z`` and Enter to quit.
|
||||||
|
|
||||||
|
|
||||||
Install easy_install command
|
Install the easy_install command
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Python has very useful :command:`easy_install` command which install 3rd
|
Python has a very useful :command:`easy_install` command which can download and
|
||||||
party library.
|
install 3rd-party libraries with a single command. This is provided by the
|
||||||
|
"distribute" project: http://pypi.python.org/pypi/distribute.
|
||||||
|
|
||||||
* http://pypi.python.org/pypi/distribute
|
To install distribute, download http://distribute.org/distribute_setup.py and
|
||||||
|
save it somewhere. After download, invoke the command prompt, go to the
|
||||||
easy_install downloads and install software which you want to need by only
|
directory with distribute_setup.py and run this command:
|
||||||
one command.
|
|
||||||
|
|
||||||
|
|
||||||
Save http://distribute.org/distribute_setup.py link by Right-click.
|
|
||||||
Some browsers can download just open the URL.
|
|
||||||
If you can read the file iteslf, calm down, Right-click and choose "Save".
|
|
||||||
|
|
||||||
After download, invoke command prompt, go to the distribute_setup.py saved
|
|
||||||
directory and run this command:
|
|
||||||
|
|
||||||
.. code-block:: bat
|
.. code-block:: bat
|
||||||
|
|
||||||
C:\> python distribute_setup.py
|
C:\> python distribute_setup.py
|
||||||
|
|
||||||
Now :command:`easy_insall` command is installed. OK, Let's go to the Sphinx
|
Now distribute and its :command:`easy_install` command is installed. From there
|
||||||
install!
|
we can go to the Sphinx install.
|
||||||
|
|
||||||
|
|
||||||
Install Sphinx
|
Installing Sphinx with easy_install
|
||||||
^^^^^^^^^^^^^^^
|
-----------------------------------
|
||||||
|
|
||||||
If you finshed easy_install install, for the rest is just a moment.
|
If you finished the installation of distribute, type this line in the command
|
||||||
Type this line.
|
prompt:
|
||||||
|
|
||||||
.. code-block:: bat
|
.. code-block:: bat
|
||||||
|
|
||||||
C:\> easy_install sphinx
|
C:\> easy_install sphinx
|
||||||
|
|
||||||
After installation, type :command:`sphinx-quickstart` on the command
|
After installation, type :command:`sphinx-build` on the command prompt. If
|
||||||
prompt. If you get interactive messages which starts with
|
everything worked fine, you will get a Sphinx version number and a list of
|
||||||
``Welcome to the Sphinx <version> quickstart utility.``,
|
options for this command.
|
||||||
installation is succeeded. Quit by hitting ``Ctrl+C``.
|
|
||||||
|
|
||||||
That it. Install is over. Let's go to :doc:`tutorial` to make Sphinx project.
|
|
||||||
|
|
||||||
|
That it. Installation is over. Head to :doc:`tutorial` to make a Sphinx
|
||||||
|
project.
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user