Adding ./doc from boost

Reviewer: Lauro Moura <lauro.neto@openbossa.org>
          Luciano Wolf <luciano.wolf@openbossa.org>

doc/howto-build/cmake-primer.rst

@@ -0,0 +1,72 @@
+
+.. _cmake-primer:
+
+************
+CMake primer
+************
+
+This chapter is a basic introduction to CMake, the build system used by PySide
+and the boost binding generator.
+
+The practical steps will focus on how to use cmake on a Unix-like (GNU/Linux)
+environment.
+
+
+Configuring
+===========
+
+Project file - CMakeLists.txt
+-----------------------------
+
+CMake parses the file CMakeLists.txt for information about the project,
+like project name, dependencies, what should be compiled, what should be
+shipped.
+
+
+CMake variables
+---------------
+
+CMake can have its default behavior modified by providing some
+
+* ``CMAKE_INSTALL_PREFIX=<some path here>`` sets the install prefix to
+  the specified path.
+* ``CMAKE_MODULE_PATH=<some path here>`` sets the extra directories
+  where CMake will try to find its modules.
+* ``CMAKE_TOOLCHAIN_FILE=<file path>`` sets the path to the file that
+  describes the toolchain used to compile this project. It is very useful
+  when using CMake with icecc to speedup compilation.
+
+You can define a variable using the ``-D<VARIABLE>`` switch like the example
+below.
+
+* ``-DCMAKE_BUILD_TYPE=Release|Debug`` sets the building behavior. Default
+  value is Release.
+
+Invoking CMake
+--------------
+
+After writing the CMakeLists.txt and deciding which flags will be used,
+you can invoke CMake using::
+
+  cmake <CMake flags> <path to toplevel CMakeLists.txt file>
+
+For example, if you use the ``build/`` folder to build the project and
+want it to be installed into ``/opt/sandbox/``, use the following lines::
+
+  cd build/
+  cmake -DCMAKE_INSTALL_PREFIX=/opt/sandbox ..
+
+CMake will process the project file and write the output files in the
+current directory
+
+Building
+========
+
+After the configuration process, the Makefiles are written and you can build
+the project using :program:`make`.
+
+Installing
+==========
+
+As in the building process, ``make install`` will install the files into
+the target directory.

doc/howto-build/index.rst

@@ -0,0 +1,19 @@
+.. PySide documentation master file, created by sphinx-quickstart on Fri Mar  6 11:45:08 2009.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Getting started with PySide
+===========================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   cmake-primer
+   setup-apiextractor
+   setup-generator
+   setup-boostpython
+   setup-bindings
+
+

doc/howto-build/setup-apiextractor.rst

@@ -0,0 +1,49 @@
+
+.. _api-extractor:
+
+**************
+API Extractor
+**************
+
+Overview
+========
+
+The **API Extractor** library is used by the binding generator to
+parse the header and typesystem files to create an internal
+representation of the API. It is based on the
+`QtScriptGenerator <http://labs.trolltech.com/page/Projects/QtScript/Generator>`_
+codebase.
+
+Getting the sources
+===================
+
+* Download URL: http://www.pyside.org/downloads/
+
+Build requirements
+==================
+
++ CMake >= 2.6.0
++ Qt4.5 libraries and development headers >= 4.5.0
++ libboost-graph >= 1.38.0
+
+Building and installing
+=======================
+
+To build and install just follow the generic cmake instructions in section
+:ref:`cmake-primer`.
+
+Debian packaging
+================
+
+In order to compile this package in a debian environment, make sure the
+following packages are installed:
+
+* debhelper (>= 5)
+* cdbs
+* cmake (>= 2.6.0)
+* libboost-graph1.38-dev (>= 1.38.0)
+* libqt4-dev (>= 4.5)
+
+And then you can build the package using::
+
+  $ dpkg-buildpackage -rfakeroot

doc/howto-build/setup-bindings.rst

@@ -0,0 +1,76 @@
+***************
+Qt 4.6 Bindings
+***************
+
+Overview
+========
+
+These bindings allow access of Qt 4.6 libraries as Python modules,
+making them available just using the ``import`` command.
+
+The build process is comprised of two stages: in a first moment the
+bindings source code are created from the Qt 4.6 headers by calling
+the :ref:`boost-python-generator` with apropriate parameters; the
+generated files are then compiled and linked together to form the
+bindings libraries.
+
+The bindings available at the moment are listed below:
+
+   + QtCore
+   + QtGui
+   + QtHelp
+   + QtMultimedia
+   + QtNetwork
+   + QtOpenGL
+   + QtScript
+   + QtScriptTools
+   + QtSql
+   + QtSvg
+   + QtUiTools
+   + QtWebKit
+   + QtXml
+   + QtXmlPatterns
+
+Getting the sources
+===================
+
+* Download URL: http://www.pyside.org/downloads/
+
+Build requirements
+==================
+
+   + CMake (>= 2.6.0)
+   + Qt 4.6 libraries + headers
+   + Boost.Python + headers (>= 1.40.0)
+   + :ref:`boost-python-generator`
+
+
+Building and installing
+=======================
+
+To build and install just follow the generic cmake instructions in
+section :ref:`cmake-primer`.
+
+Be advised that the build process can be rather lenghty because of the
+number of source files that will be compiled.
+
+Debian packaging
+================
+
+.. note:: For the time being the Debian packaging uses Qt 4.5 as dependency, therefore the generated bindings will be for this version of Qt.
+
+In order to compile this package in a debian environment, make sure the
+following packages are installed:
+
+* debhelper (>= 5)
+* cdbs
+* cmake (>= 2.6.0)
+* python-all-dev
+* python-central (>= 0.6)
+* boostpythongenerator (>= 0.3)
+* libboost-python1.40-dev (>= 1.40.0)
+* libqt4-dev (>= 4.5)
+
+And then you can build the package using::
+
+  $ dpkg-buildpackage -rfakeroot

doc/howto-build/setup-boostpython.rst

@@ -0,0 +1,51 @@
+
+.. _boost-python-generator:
+
+**********************
+Boost.Python Generator
+**********************
+
+Overview
+=========================================
+
+The **Boost::Python Generator** (A.K.A. :program:`boostpythongenerator`) is
+the program that creates the Boost.Python bindings source files from Qt headers
+and auxiliary files  (typesystems, ``global.h`` and glue files). It depends on
+:ref:`generator-runner` and :ref:`api-extractor` library.
+
+
+Getting the sources
+===================
+
+* Download URL: http://www.pyside.org/downloads/
+
+Build requirements
+==================
+
++ CMake >= 2.6.0
++ Qt4.5 libraries and development headers >= 4.5.0
++ :ref:`api-extractor` + development headers
++ :ref:`generator-runner` + development headers
+
+Building and installing
+=======================
+
+To build and install just follow the generic cmake instructions in
+section :ref:`cmake-primer`.
+
+Debian packaging
+================
+
+In order to compile this package in a debian environment, make sure the
+following packages are installed:
+
+* debhelper (>= 5)
+* cdbs
+* cmake (>= 2.6.0)
+* libqt4-dev (>= 4.5)
+* libapiextractor-dev (>= 0.3.2)
+* libgenrunner-dev (>= 0.3.2a1)
+
+And then you can build the package using::
+
+  $ dpkg-buildpackage -rfakeroot

doc/howto-build/setup-generator.rst

@@ -0,0 +1,50 @@
+
+.. _generator-runner:
+
+****************
+Generator Runner
+****************
+
+Overview
+=========================================
+
+The **Generator Runner** (A.K.A. :program:`generatorrunner`) is the
+program that controls the binding generation process according to the
+rules given by the user through headers, type system files and generator
+front-ends (such as :ref:`boost-python-generator`). It depends on
+:ref:`api-extractor` library.
+
+
+Getting the sources
+===================
+
+* Download URL: http://www.pyside.org/downloads/
+
+Build requirements
+==================
+
++ CMake >= 2.6.0
++ Qt4.5 libraries and development headers >= 4.5.0
++ :ref:`api-extractor` + development headers
+
+Building and installing
+=======================
+
+To build and install just follow the generic cmake instructions in
+section :ref:`cmake-primer`.
+
+Debian packaging
+================
+
+In order to compile this package in a debian environment, make sure the
+following packages are installed:
+
+* debhelper (>= 5)
+* cdbs
+* cmake (>= 2.6.0)
+* libqt4-dev (>= 4.5)
+* libapiextractor-dev (>= 0.3.2)
+
+And then you can build the package using::
+
+  $ dpkg-buildpackage -rfakeroot