.. project_name documentation master file, created by
   sphinx-quickstart on Sun Nov  1 14:59:49 2009.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Introduction to Sphinx 
=======================

`Sphinx <http://sphinx.pocoo.org>`_ was released in early 2008 as a
tool to process the `python documentation <http://docs.python.org/dev/>`_

*  It renders text with relatively little markup into html/pdf
*  ``LaTeX``'s math-mode is available.
*  It renders code with language-specific highlighting  (defaults
   to python)
*  provides most of the features of html and latex markup:

   -  linking 
   -  referencing (sections, arbitrary locations)
   -  indexing  (terms, objects)
   -  navigation (sections, optionally numbered)
   -  inclusion (images, tables, text, code, objects)
   -  exclusion (tag-based, e.g. for html/pdf)
   -  math-mode (e.g. :math:`e^{i\theta} = \cos(\theta) + i \sin(\theta)`)
   -  citation
   -  footnotes
   
*  By default, has a ``Show Source`` link in its Table-of-Contents panel where 
   you can *view un-rendered text*. 
*  It is being actively developed.
*  It has an active Usenet newsgroup `sphinx-dev <http://groups.google.com/group/sphinx-dev>`_.  
*  It is used by  `many projects <http://sphinx.pocoo.org/examples.html>`_ now 
   - you can learn from these.


The code depends on 

   *  :mod:`docutils` (restructured text parser),
   *  :mod:`jinja2` (templating tool) and 
   *  :mod:`pygments` (highlighter).
   *  :command:`latex` (fonts, mathematical formatting) - with the
      texlive package you'll need ``latex-recommended``,
      ``latex-extra`` and ``fonts-recommended``.

      -  see the sphinx extension docs for how to use ReportLab's 
         :mod:`rst2pdf` instead.


.. index::  autodoc, intersphinx, doctest, linkcheck

The markup extends restructured text of :mod:`docutils` - adding more
directives and roles, and linking across documents.
As with ReST, text is white-space sensitive.

It has a set of extensions which includes:

      autodoc
         extract docstrings from documented code
      intersphinx
         link documentation to other python documentation
      doctest
         run docstrings through doctest
      linkcheck
         check all hyperlinks in document tree


.. only:: html

   :download:`Download this document as pdf <../build/latex/demo_docs.pdf>`

Table of Contents
-----------------
.. toctree::
   :maxdepth: 2

   General Introduction <general/index>
   Documenting Python <python/index>


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`