.. _Installation:

************
Installation
************

The cgatreport module is an extension for :mod:`sphinx`
that provides facilities for data retrieval and data rendering
within reStructured text. 

This section explains the installation and configuration of cgatreport.

.. _Requirements:

Requirements
************

cgatreport requires the following software

* python_
* `SQLAlchemy <http://www.sqlalchemy.org/>`_
* matplotlib_
* sphinx_

Additional functionality is available if the following modules are
installed:

* `web.py <http://webpy.org>`_

Installation
************

In order to install the extension, download the latest sources from *TODO* and unpack:

   tar -xvzf sphinx-report.tar.gz

Alternatively, check out the the latest code from the subversion repository::

   svn checkout http://sphinx-report.googlecode.com/svn/trunk/ sphinx-report-read-only

To install, type::

   python setup.py build
   python setup.py install

First steps
***********

To get running quickly, use the the :file:`cgatreport-quickstart`` to
create a skeleton project in the directory ``newproject``::

   cgatreport-quickstart -d newproject

Enter ``newproject`` and build the skeleton report::

   make html

Open :file:`newproject/_build/html/index.html` in your browser 
to view the skeleton documentation. 

At this stage you can review :ref:`Configuration` options
in the file :file:`conf.py` and then start adding content
to your report. See the :ref:`Tutorials` on how to do this.

If you already have a sphinx document but would like to use the
capabilities of cgatreport, add the following entries to the variable 
:data:`extensions` in the sphinx configuration file :file:`conf.py`::

   extensions.extend( [ 'CGATReport.only_directives', 
              'CGATReport.roles',
              'CGATReport.errors_directive',
              'CGATReport.report_directive' ] )

.. _Configuration:

Configuration
*************

Sphinx and the cgatreport extension read configuration details
from the file :file:`cgatreport.ini` at the top-level of the
installation. The following variables are recognized in the
``[report]`` section:

.. glossary::

   cachedir
      string

      directoryname for cache. Set to ``None`` to disable caching.

      Example::

         cachedir=_cache

   urls
      tuple 

      urls to include within the annotation of an image. Possible values are:

      code
         add link to source code of the :term:`Tracker`
      rst
         show rst generated by cgatreport
      data
         add link to raw data. Note that this function requires that
	 active content is enabled (see :ref:`Tutorial7`)

      Example::

         urls=("code", "rst", "data")

   sql_backend
       string

       the database backend for :class:`TrackerSQL`. The backend follows
       the cgatreport`sqlalchemy` syntax. 

       Example for an sqlite connection (requires sqlite3) ::
              
          sql_backend = "sqlite:///%s/csvdb" % os.path.abspath(".")

   show_errors 

      boolean
      if set to true, show errors into the documents

   images
      tuple
      
      additional images that should be rendered. A ``,``-separated list
      of values of tuples of three values each:
      ``<name>,<suffix>,size``. The ``suffix`` determines the file
      type. For example, the following configuration will add an
      image in png format of size 200 called ``hires`` and an
      image in eps format of size 50 called ``eps``.

      images=hires,hires.png,200,eps,eps,50

Configuration options that are general for any sphinx
document are in the file :file:`conf.py`. See the `sphinx
documentation <http://sphinx.pocoo.org/config.html>`_. for a list of
all configuration options.































