Refactoring docs/index.rst into separate rst files

9 files changed, 772 insertions, 716 deletions

diff --git a/docs/building/linux.rst b/docs/building/linux.rst
new file mode 100644
index 000000000..f14512cbc
--- /dev/null
+++ b/docs/building/linux.rst
@@ -0,0 +1,150 @@
+.. _building_linux:
+
+Building PySide on a Linux System (Ubuntu 12.04 - 14.04)
+========================================================
+
+.. contents:: :local:
+
+Installing prerequisites
+------------------------
+
+#. Install build dependencies:
+
+   ::
+
+      $ sudo apt-get install build-essential git cmake libqt4-dev libphonon-dev python2.7-dev libxml2-dev libxslt1-dev qtmobility-dev
+
+#. Install latest ``pip`` distribution into the Python you
+   installed in the first step: download `get-pip.py 
+   <https://bootstrap.pypa.io/get-pip.py>`_ and run it using
+   the ``python`` interpreter of your Python 2.7 installation using a
+   command prompt:
+
+   ::
+
+      $ wget https://bootstrap.pypa.io/get-pip.py
+      $ sudo python2.7 get-pip.py
+
+#. Install latest ``wheel`` distribution:
+
+   ::
+
+      $ sudo pip2.7 install wheel
+
+
+Building PySide distribution
+----------------------------
+
+#. Download ``PySide`` source distribution:
+
+   ::
+
+      $ wget https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz
+
+#. Extract the source distribution:
+
+   ::
+
+      $ tar -xvzf PySide-1.2.2.tar.gz
+
+#. Switch to the distribution directory:
+
+   ::
+
+      $ cd PySide-1.2.2
+
+#. Build the ``wheel`` binary distribution:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4
+
+#. Optionally you can build standalone version of distribution with embedded Qt libs:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --standalone
+
+
+Building PySide distribution from a Git repository
+--------------------------------------------------
+
+#. Clone ``PySide`` setup scripts from git repository:
+
+   ::
+
+      $ git clone https://github.com/PySide/pyside-setup.git pyside-setup
+
+#. Switch to the ``pyside-setup`` directory:
+
+   ::
+
+      $ cd pyside-setup
+
+#. Build ``PySide`` distribution:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --version=1.2.2
+
+#. Optionally you can build standalone version of distribution with embedded Qt libs:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --version=1.2.2 --standalone
+
+#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4
+
+
+Installing PySide distribution
+------------------------------
+
+#. After the successful build, install the distribution with ``pip``:
+
+   ::
+
+      $ sudo pip2.7 install dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
+
+#. Run the post-install script to finish the package configuration:
+
+   ::
+
+      $ sudo python2.7 pyside_postinstall.py -install
+
+
+Installing PySide distribution into ``virtual`` Python environment
+------------------------------------------------------------------
+
+#. Install latest ``virtualenv`` distribution:
+
+   ::
+
+      $ sudo pip2.7 virtualenv
+
+#. Use ``virtualenv`` to make a workspace:
+
+   ::
+
+      $ virtualenv-2.7 env
+
+#. Switch to the ``env`` directory:
+
+   ::
+
+      $ cd env
+
+#. Install the distribution with ``pip``:
+
+   ::
+
+      $ bin/pip2.7 install ../dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
+
+#. Run the post-install script to finish the package configuration:
+
+   ::
+
+      $ bin/python bin/pyside_postinstall.py -install
diff --git a/docs/building/macosx.rst b/docs/building/macosx.rst
new file mode 100644
index 000000000..2d11c5467
--- /dev/null
+++ b/docs/building/macosx.rst
@@ -0,0 +1,276 @@
+.. _building_macosx:
+
+Building PySide on a Mac OS X System
+====================================
+
+.. contents:: :local:
+
+Mac OS X is a Unix flavor, partially based upon 
+`BSD Unix <http://en.wikipedia.org/wiki/Berkeley_Software_Distribution>`_.
+
+The supported Mac OS X versions created by `Apple <http://www.apple.com/>`_ are
+
+- OS X 10.6 *Snow Leopard*
+- OS X 10.7 *Lion*
+- OS X 10.8 *Mountain Lion*
+- OS X 10.9 *Mavericks*
+
+Mac OS X is a proprietary UNIX flavor of BSD Unix and only partially similar to
+Linux. Therefore, the usual packages from Linux distributions cannot be used
+without modifications.
+
+There are several known package managers which provide support for Mac OS X, namely
+
+- `MacPorts <http://www.macports.org/>`_
+- `Fink <http://www.finkproject.org/>`_
+- `Homebrew <http://brew.sh/>`_
+
+The main purpose of all of these projects is to provide the missing Linux packages
+for Mac OS X.
+
+Throughout this tutorial, we are only using `Homebrew <http://brew.sh/>`_, because
+it appears to be the most light-weight package manager available. All installations
+are made to /usr/local/(bin|lib|include|shared) by simple symlinks.
+
+But it should be easy to translate these instructions for the other, heavier package managers.
+
+
+Installing prerequisites
+------------------------
+
+#. Install Package Manager:
+
+   ::
+
+      $ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
+
+   Follow the on-screen instructions to make adjustions, especially run
+
+   ::
+
+      $ brew doctor
+
+   Also see the `homebrew homepage <http://brew.sh/>`_ for further information
+
+#. Install `Xcode <https://itunes.apple.com/en/app/xcode/id497799835?mt=12>`_ (optional):
+
+   Follow the on-screen instructions. If you selected any extensions to be installed,
+   wait for their completion before you proceed.
+
+   .. note::
+
+      If you are using Mavericks, you can also use the Xcode Command Line Tools without actually installing Xcode
+      (not tested, see this article: `How to Install Command Line Tools in OS X Mavericks (Without Xcode)
+      <http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/>`_).
+
+#. Install the Xcode command Line Tools:
+
+   After Xcode installation has finished, you can open a command shell and issue
+
+   ::
+
+      $ xcode-select --install
+
+   This will open a dialog window with further instructions.
+   After the command line tools are installed, you will not need to use Xcode again
+   in order to set up PySide.
+
+#. Install build dependencies:
+
+   ::
+
+      $ brew install python cmake qt
+
+   Remark: This installs ``Homebrew`` Python, which is fine for you as a single user.
+   If you are considering to build installers for external users, see the section
+   ``About PySide Distributions``.
+
+#. Install latest ``pip`` distribution into the Python you
+   installed in the first step: download `get-pip.py 
+   <https://bootstrap.pypa.io/get-pip.py>`_ and run it using
+   the ``python`` interpreter of your Python 2.7 installation using a
+   command prompt:
+
+   ::
+
+      $ wget https://bootstrap.pypa.io/get-pip.py
+      $ sudo python2.7 get-pip.py
+
+   .. note::
+
+      There are situations with older Python versions, where the above procedure does not work.
+      You can then use this last-resort work-around (tested)::
+
+         $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
+         $ sudo python2.7 ez_setup.py
+         $ sudo easy_install pip
+         $ sudo pip install setuptools -U
+         $ sudo pip install wheel -U
+
+#. Install latest ``wheel`` distribution:
+
+   ::
+
+      $ sudo pip2.7 install wheel
+
+
+About PySide Distribution
+-------------------------
+
+If you want to build PySide for your own use, the above instructions are ok.
+
+But when you are considering to build PySide for other versions or other users, you need
+to be aware of the following caveat:
+
+- Mac OS X has the concept of a ``MACOSX_DEPLOYMENT_TARGET``
+
+- The current deployment targets which work with PySide are 10.6 to 10.9 .
+
+- All binary installers from https://www.python.org are built with the setting
+
+::
+
+   $ export MACOSX_DEPLOYMENT_TARGET=10.6  # Snow Leopard
+
+- The default setting for the deployment target of an extension (like PySide)
+  is always inherited from the Python used for building.
+  You can set the deployment target higher than that, but not below the
+  OS X version that was set during building your Python installation.
+  
+- Current distributions like Homebrew set the deployment target to the same
+  value as the OS version they are built with. (I.E. 10.9 for Mavericks).
+  
+- Example: A PySide, built on Mavericks, will therefore not run on a Python that was built
+  for Mountain Lion.
+
+Recommendation:
+
+- Use Homebrew's simplicity for your own machine. Do not use it for distributing.
+
+- Use one of the `Python.org Distributions <https://www.python.org/downloads/>`_
+  or 
+  
+- Build your own Python, either from a tar archive (
+  `Python 2.7 <https://www.python.org/ftp/python/2.7.6/Python-2.7.6.tgz>`_ or
+  `Python 3.4 <https://www.python.org/ftp/python/3.4.0/Python-3.4.0.tgz>`_), or from a
+  `Mercurial repository <https://docs.python.org/devguide/>`_ with an explicit setting of
+  ``MACOSX_DEPLOYMENT_TARGET``.
+
+Building PySide distribution
+----------------------------
+
+#. Download ``PySide`` source distribution:
+
+   ::
+
+      $ wget https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz
+
+#. Extract the source distribution:
+
+   ::
+
+      $ tar -xvzf PySide-1.2.2.tar.gz
+
+#. Switch to the distribution directory:
+
+   ::
+
+      $ cd PySide-1.2.2
+
+#. Build the ``wheel`` binary distribution:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel
+
+
+Building PySide distribution from a Git repository
+--------------------------------------------------
+
+#. Clone ``PySide`` setup scripts from git repository:
+
+   ::
+
+      $ git clone https://github.com/PySide/pyside-setup.git pyside-setup
+
+#. Switch to the ``pyside-setup`` directory:
+
+   ::
+
+      $ cd pyside-setup
+
+#. Build ``PySide`` distribution:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel --version=1.2.2
+
+   ..  commented out, working on this
+        #. Optionally you can build standalone version of distribution with embedded Qt libs:
+        
+           ::
+        
+              $ python2.7 setup.py bdist_wheel --version=1.2.2 --standalone
+
+#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
+
+   ::
+
+      $ python2.7 setup.py bdist_wheel
+
+
+Installing PySide distribution
+------------------------------
+
+#. After the successful build, install the distribution with ``pip``:
+
+   ::
+
+      $ sudo pip2.7 install dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
+
+#. Run the post-install script to finish the package configuration:
+   
+   ::
+
+      $ sudo python2.7 pyside_postinstall.py -install
+
+
+Installing PySide distribution into ``virtual`` Python environment
+------------------------------------------------------------------
+
+#. Install latest ``virtualenv`` distribution:
+
+   ::
+
+      $ sudo pip2.7 virtualenv
+
+#. Use ``virtualenv`` to make a workspace:
+
+   ::
+
+      $ virtualenv-2.7 env
+
+#. Activate the virtual Python in the ``env`` directory:
+
+   ::
+
+      $ source env/bin/activate
+
+#. Install the distribution with ``pip``:
+
+   ::
+
+      (env) $ pip install ../dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
+
+#. Run the post-install script to finish the package configuration:
+
+   ::
+
+      (env) $ pyside_postinstall.py -install
+
+#. Leave the virtual environment (optional):
+
+   ::
+
+      (env) $ deactivate
+      $ 
diff --git a/docs/building/options.rst b/docs/building/options.rst
new file mode 100644
index 000000000..0080a367e
--- /dev/null
+++ b/docs/building/options.rst
@@ -0,0 +1,101 @@
+.. _building_options:
+
+PySide Setup Script command line options
+========================================
+
+.. contents:: :local:
+
+Usage on a Windows System
+-------------------------
+
+::
+
+   c:\> c:\Python27\python.exe setup.py [distribution_type] [options]
+
+Usage on a Linux/Mac OS X System
+--------------------------------
+
+::
+
+   python2.7 setup.py [distribution_type] [options]
+
+
+Distribution types
+------------------
+
+``bdist_wheel``
+    Create a wheel binary distribution.
+    This distribution type can be installed with ``pip``.
+
+``bdist_egg``
+    Create an egg binary distribution.
+    This distribution type can be installed with ``easy_install``.
+
+``bdist_wininst``
+    Create a standalone windows installer with embedded Qt libs and development tools.
+    This distribution type can be installed with ``easy_install``.
+
+``install``
+    Install package to site packages folder.
+
+``develop``
+    Install package in ``development mode``, such that it's available on
+    ``sys.path``, yet can still be edited directly from its source folder.
+
+``sdist``
+    Create a full source distribution with included sources of PySide Setup Scripts,
+    PySide, Shiboken, PySide Tools and PySide Examples.
+    Can be used to build binary distribution in offline mode.
+
+Options
+-------
+
+``--qmake``
+    Specify the path to qmake.
+    Useful when the qmake is not in path or more than one Qt versions are installed.
+
+``--openssl``
+    Specify the path to OpenSSL libs.
+
+``--only-package``
+    Skip rebuilding everything and create distribution from prebuilt binaries.
+    Before using this option first time, the full distribution build is required.
+
+``--cmake``
+    Specify the path to cmake.
+    Useful when the cmake is not in path.
+
+``--standalone``
+    When enabled, all required Qt libs will be included in PySide distribution.
+    This option is allways enabled on Windows.
+    On Linux it's disabled by default.
+
+    .. note::
+
+      This option does not work on Mac OS X, yet.
+
+``--version``
+    Specify what version of PySide distribution to build.
+    This option is available only when the setup scripts are cloned from git repository.
+
+``--list-versions``
+    List available versions of PySide distributions.
+
+``--ignore-git``
+    Don't pull sources from git repository.
+
+``--make-spec``
+    Specify the cmake makefile generator type.
+    Available values are ``msvc`` on Windows and ``make`` on Linux/Mac OS X.
+
+``--no-examples``
+    Don't include PySide examples in PySide distribution
+
+``--jobs``
+    Specify the number of parallel build jobs
+
+``--jom``
+    Use `jom <http://qt-project.org/wiki/jom>`_ instead of nmake with msvc
+
+``--build-tests``
+    Enable building the tests
diff --git a/docs/building/windows.rst b/docs/building/windows.rst
new file mode 100644
index 000000000..bc512ae13
--- /dev/null
+++ b/docs/building/windows.rst
@@ -0,0 +1,138 @@
+.. _building_windows:
+
+Building PySide on a Windows System
+===================================
+
+.. contents:: :local:
+
+Installing prerequisites
+------------------------
+
+#. Install `Python
+   <http://www.python.org/download/>`_.
+
+#. Install `Qt 4.8 libraries for Windows VS 2008 edition
+   <http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-win-opensource-4.8.5-vs2008.exe>`_
+   when building against Python 2.6, 2.7 or 3.2.
+   
+   Install `Qt 4.8 libraries for Windows VS 2010 edition
+   <http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-win-opensource-4.8.5-vs2010.exe>`_
+   when building against Python 3.3 or 3.4.
+
+#. Install `Cmake
+   <http://www.cmake.org/cmake/resources/software.html>`_.
+
+#. Install `Windows SDK v7.0
+   <http://www.microsoft.com/en-us/download/details.aspx?id=3138>`_
+   when building against Python 2.6, 2.7 or 3.2.
+   
+   Install `Windows SDK v7.1
+   <http://www.microsoft.com/en-us/download/details.aspx?id=8279>`_
+   when building against Python 3.3 or 3.4.
+
+#. Install `Git
+   <http://git-scm.com/download/win>`_.
+
+#. (Optional) Install `OpenSSL
+   <http://slproweb.com/products/Win32OpenSSL.html>`_.
+
+#. Install latest ``pip`` distribution into the Python you
+   installed in the first step: download `get-pip.py 
+   <https://bootstrap.pypa.io/get-pip.py>`_ and run it using
+   the ``python`` interpreter of your Python 2.7 installation using a
+   command prompt:
+
+   ::
+
+      c:\> c:\Python27\python get-pip.py
+
+#. Install latest `wheel` distribution:
+
+   ::
+
+      c:\> c:\Python27\Scripts\pip install wheel
+
+
+Building PySide distribution
+----------------------------
+
+#. Download and extract `PySide source distribution
+   <https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz>`_
+
+#. Switch to the distribution directory:
+
+   ::
+
+      c:\> cd PySide-1.2.2
+
+#. Build the ``wheel`` binary distribution:
+
+   ::
+
+      c:\> c:\Python27\python.exe setup.py bdist_wheel --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
+
+
+Building PySide distribution from a Git repository
+--------------------------------------------------
+
+#. Clone ``PySide`` setup scripts from git repository:
+
+   ::
+
+      c:\> git clone https://github.com/PySide/pyside-setup.git pyside-setup
+
+#. Switch to the ``pyside-setup`` directory:
+
+   ::
+
+      c:\> cd pyside-setup
+
+#. Build the `wheel` binary distribution:
+
+   ::
+
+      c:\> c:\Python27\python.exe setup.py bdist_wheel --version=1.2.2 --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
+
+#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
+
+   ::
+
+      c:\> c:\Python27\python.exe setup.py bdist_wheel --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
+
+
+Installing PySide distribution
+------------------------------
+
+#. After the successful build, install the distribution with ``pip``:
+
+   ::
+
+      c:\> c:\Python27\Scripts\pip install dist\PySide-1.2.2-cp27-none-win32.whl
+
+
+Installing PySide distribution into ``virtual`` Python environment
+------------------------------------------------------------------
+
+#. Install latest ``virtualenv`` distribution:
+
+   ::
+
+      c:\> c:\Python27\Scripts\pip install virtualenv
+
+#. Use ``virtualenv`` to make a workspace:
+
+   ::
+
+      c:\> c:\Python27\Scripts\virtualenv env
+
+#. Switch to the ``env`` directory:
+
+   ::
+
+      c:\> cd env
+
+#. Install the distribution with ``pip``:
+
+   ::
+
+      c:\> Scripts\pip install ..\dist\PySide-1.2.2-cp27-none-win32.whl
diff --git a/docs/changes.rst b/docs/changes.rst
new file mode 100644
index 000000000..d9e113ec6
--- /dev/null
+++ b/docs/changes.rst
@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst
diff --git a/docs/index.rst b/docs/index.rst
index 521ca0617..bdfb7287a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,6 +2,8 @@
 PySide
 ======
 
+*Python bindings for the Qt cross-platform application and UI framework*
+
 .. image:: https://pypip.in/wheel/PySide/badge.png
    :target: https://pypi.python.org/pypi/PySide/
    :alt: Wheel Status
@@ -43,729 +45,28 @@ PySide requires Python 2.6 or later and Qt 4.6 or better.
 
    Qt 5.x is currently not supported.
 
-Installation
-============
-
-Installing prerequisites
-------------------------
-
-Install latest ``pip`` distribution: download `get-pip.py
-<https://bootstrap.pypa.io/get-pip.py>`_ and run it using
-the ``python`` interpreter.
-
-Installing PySide on a Windows System
--------------------------------------
-
-To install PySide on Windows you can choose from the following options:
-
-#. Use pip to install the ``wheel`` binary packages:
-
-   ::
-
-      pip install -U PySide
-
-#. Use setuptools to install the ``egg`` binary packages (deprecated):
-
-   ::
-
-      easy_install -U PySide
-
-.. note::
-
-   Provided binaries are without any other external dependencies.
-   All required Qt libraries, development tools and examples are included.
-
-
-Installing PySide on a Mac OS X System
---------------------------------------
-
-You need to install or build Qt 4.8 first, see the `Qt Project Documentation
-<http://qt-project.org/doc/qt-4.8/install-mac.html>`_.
-
-Alternatively you can use `Homebrew <http://brew.sh/>`_ and install Qt with
-
-::
-
-   $ brew install qt
-
-To install PySide on Mac OS X you can choose from the following options:
-
-#. Use pip to install the ``wheel`` binary packages:
-
-   ::
-
-      $ pip install -U PySide
-
-
-After the installation, the following call must be made manually:
-
-::
-
-   $ pyside_postinstall.py -install
-
-
-Installing PySide on a Linux System
------------------------------------
-
-We do not provide binaries for Linux. Please read the build instructions in section
-``Building PySide on a Linux System``.
-
-
-Building PySide on a Windows System
-===================================
-
-Windows: Installing prerequisites
----------------------------------
-
-#. Install `Python
-   <http://www.python.org/download/>`_.
-
-#. Install `Qt 4.8 libraries for Windows VS 2008 edition
-   <http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-win-opensource-4.8.5-vs2008.exe>`_
-   when building against Python 2.6, 2.7 or 3.2.
-   
-   Install `Qt 4.8 libraries for Windows VS 2010 edition
-   <http://download.qt-project.org/official_releases/qt/4.8/4.8.5/qt-win-opensource-4.8.5-vs2010.exe>`_
-   when building against Python 3.3 or 3.4.
-
-#. Install `Cmake
-   <http://www.cmake.org/cmake/resources/software.html>`_.
-
-#. Install `Windows SDK v7.0
-   <http://www.microsoft.com/en-us/download/details.aspx?id=3138>`_
-   when building against Python 2.6, 2.7 or 3.2.
-   
-   Install `Windows SDK v7.1
-   <http://www.microsoft.com/en-us/download/details.aspx?id=8279>`_
-   when building against Python 3.3 or 3.4.
-
-#. Install `Git
-   <http://git-scm.com/download/win>`_.
-
-#. (Optional) Install `OpenSSL
-   <http://slproweb.com/products/Win32OpenSSL.html>`_.
-
-#. Install latest ``pip`` distribution into the Python you
-   installed in the first step: download `get-pip.py 
-   <https://bootstrap.pypa.io/get-pip.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.7 installation using a
-   command prompt:
-
-   ::
-
-      c:\> c:\Python27\python get-pip.py
-
-#. Install latest `wheel` distribution:
-
-   ::
-
-      c:\> c:\Python27\Scripts\pip install wheel
-
-
-Windows: Building PySide distribution
--------------------------------------
-
-#. Download and extract `PySide source distribution
-   <https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz>`_
-
-#. Switch to the distribution directory:
-
-   ::
-
-      c:\> cd PySide-1.2.2
-
-#. Build the ``wheel`` binary distribution:
-
-   ::
-
-      c:\> c:\Python27\python.exe setup.py bdist_wheel --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
-
-
-Windows: Building PySide distribution from a Git repository
------------------------------------------------------------
-
-#. Clone ``PySide`` setup scripts from git repository:
-
-   ::
-
-      c:\> git clone https://github.com/PySide/pyside-setup.git pyside-setup
-
-#. Switch to the ``pyside-setup`` directory:
-
-   ::
-
-      c:\> cd pyside-setup
-
-#. Build the `wheel` binary distribution:
-
-   ::
-
-      c:\> c:\Python27\python.exe setup.py bdist_wheel --version=1.2.2 --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
-
-#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
-
-   ::
-
-      c:\> c:\Python27\python.exe setup.py bdist_wheel --qmake=c:\Qt\4.8.5\bin\qmake.exe --openssl=c:\OpenSSL32bit\bin
-
-
-Windows: Installing PySide distribution
----------------------------------------
-
-#. After the successful build, install the distribution with ``pip``:
-
-   ::
-
-      c:\> c:\Python27\Scripts\pip install dist\PySide-1.2.2-cp27-none-win32.whl
-
-
-Windows: Installing PySide distribution into ``virtual`` Python environment
----------------------------------------------------------------------------
-
-#. Install latest ``virtualenv`` distribution:
-
-   ::
-
-      c:\> c:\Python27\Scripts\pip install virtualenv
-
-#. Use ``virtualenv`` to make a workspace:
-
-   ::
-
-      c:\> c:\Python27\Scripts\virtualenv env
-
-#. Switch to the ``env`` directory:
-
-   ::
-
-      c:\> cd env
-
-#. Install the distribution with ``pip``:
-
-   ::
-
-      c:\> Scripts\pip install ..\dist\PySide-1.2.2-cp27-none-win32.whl
-
-
-Building PySide on a Mac OS X System
-====================================
-
-Mac OS X is a Unix flavor, partially based upon 
-`BSD Unix <http://en.wikipedia.org/wiki/Berkeley_Software_Distribution>`_.
-
-The supported Mac OS X versions created by `Apple <http://www.apple.com/>`_ are
-
-- OS X 10.6 *Snow Leopard*
-- OS X 10.7 *Lion*
-- OS X 10.8 *Mountain Lion*
-- OS X 10.9 *Mavericks*
-
-Mac OS X is a proprietary UNIX flavor of BSD Unix and only partially similar to
-Linux. Therefore, the usual packages from Linux distributions cannot be used
-without modifications.
-
-There are several known package managers which provide support for Mac OS X, namely
-
-- `MacPorts <http://www.macports.org/>`_
-- `Fink <http://www.finkproject.org/>`_
-- `Homebrew <http://brew.sh/>`_
-
-The main purpose of all of these projects is to provide the missing Linux packages
-for Mac OS X.
-
-Throughout this tutorial, we are only using `Homebrew <http://brew.sh/>`_, because
-it appears to be the most light-weight package manager available. All installations
-are made to /usr/local/(bin|lib|include|shared) by simple symlinks.
-
-But it should be easy to translate these instructions for the other, heavier package managers.
-
-
-Mac OS X: Installing prerequisites
-----------------------------------
-
-#. Install Package Manager:
-
-   ::
-
-      $ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
-
-   Follow the on-screen instructions to make adjustions, especially run
-
-   ::
-
-      $ brew doctor
-
-   Also see the `homebrew homepage <http://brew.sh/>`_ for further information
-
-#. Install `Xcode <https://itunes.apple.com/en/app/xcode/id497799835?mt=12>`_ (optional):
-
-   Follow the on-screen instructions. If you selected any extensions to be installed,
-   wait for their completion before you proceed.
-
-   .. note::
-
-      If you are using Mavericks, you can also use the Xcode Command Line Tools without actually installing Xcode
-      (not tested, see this article: `How to Install Command Line Tools in OS X Mavericks (Without Xcode)
-      <http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/>`_).
-
-#. Install the Xcode command Line Tools:
-
-   After Xcode installation has finished, you can open a command shell and issue
-
-   ::
-
-      $ xcode-select --install
-
-   This will open a dialog window with further instructions.
-   After the command line tools are installed, you will not need to use Xcode again
-   in order to set up PySide.
-
-#. Install build dependencies:
-
-   ::
-
-      $ brew install python cmake qt
-
-   Remark: This installs ``Homebrew`` Python, which is fine for you as a single user.
-   If you are considering to build installers for external users, see the section
-   ``About PySide Distributions``.
-
-#. Install latest ``pip`` distribution into the Python you
-   installed in the first step: download `get-pip.py 
-   <https://bootstrap.pypa.io/get-pip.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.7 installation using a
-   command prompt:
-
-   ::
-
-      $ wget https://bootstrap.pypa.io/get-pip.py
-      $ sudo python2.7 get-pip.py
-
-   .. note::
-
-      There are situations with older Python versions, where the above procedure does not work.
-      You can then use this last-resort work-around (tested)::
-
-         $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py
-         $ sudo python2.7 ez_setup.py
-         $ sudo easy_install pip
-         $ sudo pip install setuptools -U
-         $ sudo pip install wheel -U
-
-#. Install latest ``wheel`` distribution:
-
-   ::
-
-      $ sudo pip2.7 install wheel
-
-
-Mac OS X: About PySide Distribution
------------------------------------
-
-If you want to build PySide for your own use, the above instructions are ok.
-
-But when you are considering to build PySide for other versions or other users, you need
-to be aware of the following caveat:
-
-- Mac OS X has the concept of a ``MACOSX_DEPLOYMENT_TARGET``
-
-- The current deployment targets which work with PySide are 10.6 to 10.9 .
-
-- All binary installers from https://www.python.org are built with the setting
-
-::
-
-   $ export MACOSX_DEPLOYMENT_TARGET=10.6  # Snow Leopard
-
-- The default setting for the deployment target of an extension (like PySide)
-  is always inherited from the Python used for building.
-  You can set the deployment target higher than that, but not below the
-  OS X version that was set during building your Python installation.
-  
-- Current distributions like Homebrew set the deployment target to the same
-  value as the OS version they are built with. (I.E. 10.9 for Mavericks).
-  
-- Example: A PySide, built on Mavericks, will therefore not run on a Python that was built
-  for Mountain Lion.
-
-Recommendation:
-
-- Use Homebrew's simplicity for your own machine. Do not use it for distributing.
-
-- Use one of the `Python.org Distributions <https://www.python.org/downloads/>`_
-  or 
-  
-- Build your own Python, either from a tar archive (
-  `Python 2.7 <https://www.python.org/ftp/python/2.7.6/Python-2.7.6.tgz>`_ or
-  `Python 3.4 <https://www.python.org/ftp/python/3.4.0/Python-3.4.0.tgz>`_), or from a
-  `Mercurial repository <https://docs.python.org/devguide/>`_ with an explicit setting of
-  ``MACOSX_DEPLOYMENT_TARGET``.
-
-Mac OS X: Building PySide distribution
---------------------------------------
-
-#. Download ``PySide`` source distribution:
-
-   ::
-
-      $ wget https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz
-
-#. Extract the source distribution:
-
-   ::
+Installing PySide
+=================
 
-      $ tar -xvzf PySide-1.2.2.tar.gz
+.. toctree::
+   :maxdepth: 2
 
-#. Switch to the distribution directory:
+   installing/windows.rst
+   installing/macosx.rst
+   installing/linux.rst
 
-   ::
 
-      $ cd PySide-1.2.2
+Building PySide
+===============
 
-#. Build the ``wheel`` binary distribution:
+.. toctree::
+   :maxdepth: 2
 
-   ::
+   building/windows.rst
+   building/macosx.rst
+   building/linux.rst
+   building/options.rst
 
-      $ python2.7 setup.py bdist_wheel
-
-
-Mac OS X: Building PySide distribution from a Git repository
-------------------------------------------------------------
-
-#. Clone ``PySide`` setup scripts from git repository:
-
-   ::
-
-      $ git clone https://github.com/PySide/pyside-setup.git pyside-setup
-
-#. Switch to the ``pyside-setup`` directory:
-
-   ::
-
-      $ cd pyside-setup
-
-#. Build ``PySide`` distribution:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel --version=1.2.2
-
-   ..  commented out, working on this
-        #. Optionally you can build standalone version of distribution with embedded Qt libs:
-        
-           ::
-        
-              $ python2.7 setup.py bdist_wheel --version=1.2.2 --standalone
-
-#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel
-
-
-Mac OS X: Installing PySide distribution
-----------------------------------------
-
-#. After the successful build, install the distribution with ``pip``:
-
-   ::
-
-      $ sudo pip2.7 install dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
-
-#. Run the post-install script to finish the package configuration:
-   
-   ::
-
-      $ sudo python2.7 pyside_postinstall.py -install
-
-
-Mac OS X: Installing PySide distribution into ``virtual`` Python environment
-----------------------------------------------------------------------------
-
-#. Install latest ``virtualenv`` distribution:
-
-   ::
-
-      $ sudo pip2.7 virtualenv
-
-#. Use ``virtualenv`` to make a workspace:
-
-   ::
-
-      $ virtualenv-2.7 env
-
-#. Activate the virtual Python in the ``env`` directory:
-
-   ::
-
-      $ source env/bin/activate
-
-#. Install the distribution with ``pip``:
-
-   ::
-
-      (env) $ pip install ../dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
-
-#. Run the post-install script to finish the package configuration:
-
-   ::
-
-      (env) $ pyside_postinstall.py -install
-
-#. Leave the virtual environment (optional):
-
-   ::
-
-      (env) $ deactivate
-      $ 
-
-
-Building PySide on a Linux System (Ubuntu 12.04 - 14.04)
-========================================================
-
-Linux: Installing prerequisites
--------------------------------
-
-#. Install build dependencies:
-
-   ::
-
-      $ sudo apt-get install build-essential git cmake libqt4-dev libphonon-dev python2.7-dev libxml2-dev libxslt1-dev qtmobility-dev
-
-#. Install latest ``pip`` distribution into the Python you
-   installed in the first step: download `get-pip.py 
-   <https://bootstrap.pypa.io/get-pip.py>`_ and run it using
-   the ``python`` interpreter of your Python 2.7 installation using a
-   command prompt:
-
-   ::
-
-      $ wget https://bootstrap.pypa.io/get-pip.py
-      $ sudo python2.7 get-pip.py
-
-#. Install latest ``wheel`` distribution:
-
-   ::
-
-      $ sudo pip2.7 install wheel
-
-
-Linux: Building PySide distribution
------------------------------------
-
-#. Download ``PySide`` source distribution:
-
-   ::
-
-      $ wget https://pypi.python.org/packages/source/P/PySide/PySide-1.2.2.tar.gz
-
-#. Extract the source distribution:
-
-   ::
-
-      $ tar -xvzf PySide-1.2.2.tar.gz
-
-#. Switch to the distribution directory:
-
-   ::
-
-      $ cd PySide-1.2.2
-
-#. Build the ``wheel`` binary distribution:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4
-
-#. Optionally you can build standalone version of distribution with embedded Qt libs:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --standalone
-
-
-Linux: Building PySide distribution from a Git repository
----------------------------------------------------------
-
-#. Clone ``PySide`` setup scripts from git repository:
-
-   ::
-
-      $ git clone https://github.com/PySide/pyside-setup.git pyside-setup
-
-#. Switch to the ``pyside-setup`` directory:
-
-   ::
-
-      $ cd pyside-setup
-
-#. Build ``PySide`` distribution:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --version=1.2.2
-
-#. Optionally you can build standalone version of distribution with embedded Qt libs:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4 --version=1.2.2 --standalone
-
-#. To build the development version of ``PySide`` distribution, ignore the --version parameter:
-
-   ::
-
-      $ python2.7 setup.py bdist_wheel --qmake=/usr/bin/qmake-qt4
-
-
-Linux: Installing PySide distribution
--------------------------------------
-
-#. After the successful build, install the distribution with ``pip``:
-
-   ::
-
-      $ sudo pip2.7 install dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
-
-#. Run the post-install script to finish the package configuration:
-
-   ::
-
-      $ sudo python2.7 pyside_postinstall.py -install
-
-
-Linux: Installing PySide distribution into ``virtual`` Python environment
--------------------------------------------------------------------------
-
-#. Install latest ``virtualenv`` distribution:
-
-   ::
-
-      $ sudo pip2.7 virtualenv
-
-#. Use ``virtualenv`` to make a workspace:
-
-   ::
-
-      $ virtualenv-2.7 env
-
-#. Switch to the ``env`` directory:
-
-   ::
-
-      $ cd env
-
-#. Install the distribution with ``pip``:
-
-   ::
-
-      $ bin/pip2.7 install ../dist/PySide-1.2.2-cp27-none-linux-x86_64.whl
-
-#. Run the post-install script to finish the package configuration:
-
-   ::
-
-      $ bin/python bin/pyside_postinstall.py -install
-
-
-PySide Setup Script command line options
-========================================
-
-Usage on a Windows System
--------------------------
-
-::
-
-   c:\> c:\Python27\python.exe setup.py [distribution_type] [options]
-
-Usage on a Linux/Mac OS X System
---------------------------------
-
-::
-
-   python2.7 setup.py [distribution_type] [options]
-
-
-Distribution types
-------------------
-
-``bdist_wheel``
-    Create a wheel binary distribution.
-    This distribution type can be installed with ``pip``.
-
-``bdist_egg``
-    Create an egg binary distribution.
-    This distribution type can be installed with ``easy_install``.
-
-``bdist_wininst``
-    Create a standalone windows installer with embedded Qt libs and development tools.
-    This distribution type can be installed with ``easy_install``.
-
-``install``
-    Install package to site packages folder.
-
-``develop``
-    Install package in ``development mode``, such that it's available on
-    ``sys.path``, yet can still be edited directly from its source folder.
-
-``sdist``
-    Create a full source distribution with included sources of PySide Setup Scripts,
-    PySide, Shiboken, PySide Tools and PySide Examples.
-    Can be used to build binary distribution in offline mode.
-
-Options
--------
-
-``--qmake``
-    Specify the path to qmake.
-    Useful when the qmake is not in path or more than one Qt versions are installed.
-
-``--openssl``
-    Specify the path to OpenSSL libs.
-
-``--only-package``
-    Skip rebuilding everything and create distribution from prebuilt binaries.
-    Before using this option first time, the full distribution build is required.
-
-``--cmake``
-    Specify the path to cmake.
-    Useful when the cmake is not in path.
-
-``--standalone``
-    When enabled, all required Qt libs will be included in PySide distribution.
-    This option is allways enabled on Windows.
-    On Linux it's disabled by default.
-
-    .. note::
-
-      This option does not work on Mac OS X, yet.
-
-``--version``
-    Specify what version of PySide distribution to build.
-    This option is available only when the setup scripts are cloned from git repository.
-
-``--list-versions``
-    List available versions of PySide distributions.
-
-``--ignore-git``
-    Don't pull sources from git repository.
-
-``--make-spec``
-    Specify the cmake makefile generator type.
-    Available values are ``msvc`` on Windows and ``make`` on Linux/Mac OS X.
-
-``--no-examples``
-    Don't include PySide examples in PySide distribution
-
-``--jobs``
-    Specify the number of parallel build jobs
-
-``--jom``
-    Use `jom <http://qt-project.org/wiki/jom>`_ instead of nmake with msvc
-
-``--build-tests``
-    Enable building the tests
 
 Feedback and getting involved
 =============================
@@ -773,3 +74,12 @@ Feedback and getting involved
 - Mailing list: http://lists.qt-project.org/mailman/listinfo/pyside
 - Issue tracker: https://bugreports.qt-project.org/browse/PYSIDE
 - Code Repository: http://qt.gitorious.org/pyside
+
+
+Changes
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   changes.rst
diff --git a/docs/installing/linux.rst b/docs/installing/linux.rst
new file mode 100644
index 000000000..2fefd7c42
--- /dev/null
+++ b/docs/installing/linux.rst
@@ -0,0 +1,9 @@
+.. _installing_linux:
+
+Installing PySide on a Linux System
+===================================
+
+We do not provide binaries for Linux. Please read
+the build instructions in section
+`Building PySide on a Linux System
+<http://pyside.readthedocs.org/en/latest/building/linux.html>`_.
diff --git a/docs/installing/macosx.rst b/docs/installing/macosx.rst
new file mode 100644
index 000000000..4e44e995f
--- /dev/null
+++ b/docs/installing/macosx.rst
@@ -0,0 +1,38 @@
+.. _installing_macosx:
+
+Installing PySide on a Mac OS X System
+======================================
+
+Installing prerequisites
+------------------------
+
+Install latest ``pip`` distribution: download `get-pip.py
+<https://bootstrap.pypa.io/get-pip.py>`_ and run it using
+the ``python`` interpreter.
+
+You need to install or build Qt 4.8 first, see the `Qt Project Documentation
+<http://qt-project.org/doc/qt-4.8/install-mac.html>`_.
+
+Alternatively you can use `Homebrew <http://brew.sh/>`_ and install Qt with
+
+::
+
+   $ brew install qt
+
+Installing PySide
+-----------------
+
+To install PySide on Mac OS X you can choose from the following options:
+
+#. Use pip to install the ``wheel`` binary packages:
+
+   ::
+
+      $ pip install -U PySide
+
+
+After the installation, the following call must be made manually:
+
+::
+
+   $ pyside_postinstall.py -install
diff --git a/docs/installing/windows.rst b/docs/installing/windows.rst
new file mode 100644
index 000000000..899e2e356
--- /dev/null
+++ b/docs/installing/windows.rst
@@ -0,0 +1,33 @@
+.. _installing_windows:
+
+Installing PySide on a Windows System
+=====================================
+
+Installing prerequisites
+------------------------
+
+Install latest ``pip`` distribution: download `get-pip.py
+<https://bootstrap.pypa.io/get-pip.py>`_ and run it using
+the ``python`` interpreter.
+
+Installing PySide
+-----------------
+
+To install PySide on Windows you can choose from the following options:
+
+#. Use pip to install the ``wheel`` binary packages:
+
+   ::
+
+      pip install -U PySide
+
+#. Use setuptools to install the ``egg`` binary packages (deprecated):
+
+   ::
+
+      easy_install -U PySide
+
+.. note::
+
+   Provided binaries are without any other external dependencies.
+   All required Qt libraries, development tools and examples are included.