Documentation: Introduction

3 files changed, 92 insertions, 33 deletions

diff --git a/docs/source/api.rst b/docs/source/api.rst
index 3bce389..1de31c0 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -10,3 +10,14 @@ The :mod:`sqlparse` module provides the following functions on module-level.
 .. autofunction:: sqlparse.parse
 
 
+.. _formatting:
+
+Formatting of SQL Statements
+----------------------------
+
+
+.. _analyze:
+
+Analyzing the Parsed Statement
+------------------------------
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 40e99e0..0e74763 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -3,10 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to python-sqlparse's documentation!
-===========================================
-
-Contents:
+python-sqlparse's documentation contents
+========================================
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 3d7a888..931659f 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -2,44 +2,58 @@ Introduction
 ============
 
 :mod:`sqlparse` is a non-validating SQL parser for Python.
-
 It provides support for parsing, splitting and formatting SQL statements.
-
-:mod:`sqlparse` is released under the terms of the
+The module is released under the terms of the
 `New BSD license <http://www.opensource.org/licenses/bsd-license.php>`_.
 
-Visit http://sqlformat.appspot.com to try it's formatting features.
+Visit the project page at http://python-sqlparse.googlecode.com for
+further information about this project.
 
 
 Download & Installation
 -----------------------
 
-To download and install :mod:`sqlparse` on your system run the following
-commands:
+The latest released version can be obtained from the
+`downloads page <http://code.google.com/p/python-sqlparse/downloads/list>`_
+on the project's website. To extract the source archive and to install
+the module on your system run
 
 .. code-block:: bash
 
-  $ git clone git://github.com/andialbrecht/python-sqlparse.git
-  $ cd python-sqlparse.git/
-  $ sudo python setup.py install
+   $ tar cvfz python-sqlparse-VERSION.tar.gz
+   $ cd python-sqlparse/
+   $ sudo python setup.py install
+
+Alternatively you can install :mod:`sqlparse` from the
+`Python Packge Index <http://pypi.python.org/pypi/sqlparse>`_ with your
+favorite tool for installing Python modules. For example when using
+`pip <http://pypi.python.org/pypi/pip>`_ run :command:`pip install sqlparse`.
 
-A tarball of the current sources is available under the following URL:
-http://github.com/andialbrecht/python-sqlparse/tarball/master
 
+Getting Started
+---------------
 
-Example Usage
--------------
+The :mod:`sqlparse` module provides three simple functions on module level
+to achieve some common tasks when working with SQL statements.
+This section shows some simple usage examples of these functions.
 
-Here are some usage examples of this module.
+Let's get started with splitting a string containing one or more SQL
+statements into a list of single statements using :meth:`~sqlparse.split`:
 
-Splitting statements::
+.. code-block:: python
 
   >>> import sqlparse
   >>> sql = 'select * from foo; select * from bar;'
   >>> sqlparse.split(sql)
-  <<< [u'select * from foo; ', u'select * from bar;']
+  [u'select * from foo; ', u'select * from bar;']
+
+The end of a statement is identified by the occurrence of a semicolon.
+Semicolons within certain SQL constructs like ``BEGIN ... END`` blocks
+are handled correctly by the splitting mechanism.
+
+SQL statements can be beautified by using the :meth:`~sqlarse.format` function.
 
-Formatting statemtents::
+.. code-block:: python
 
   >>> sql = 'select * from foo where id in (select id from bar);'
   >>> print sqlparse.format(sql, reindent=True, keyword_case='upper')
@@ -49,18 +63,37 @@ Formatting statemtents::
     (SELECT id
      FROM bar);
 
-Now, let's have a deeper look at the internals::
+In this case all keywords in the given SQL are uppercased and the
+indentation is changed to make it more readable. Read :ref:`formatting` for
+a full reference of supported options given as keyword arguments
+to that function.
+
+Before proceeding with a closer look at the internal representation of
+SQL statements, you should be aware that this SQL parser is intentionally
+non-validating. It assumes that the given input is at least some kind
+of SQL and then it tries to analyze as much as possible without making
+too much assumptions about the concrete dialect or the actual statement.
+At least it's up to the user of this API to interpret the results right.
+
+When using the :meth:`~sqlparse.parse` function a tuple of
+:class:`~sqlparse.sql.Statement` instances is returned:
+
+.. code-block:: python
 
   >>> sql = 'select * from "someschema"."mytable" where id = 1'
-  >>> pared = sqlparse.parse(sql)
-  >>> pared
-  <<< (<Statement 'select...' at 0x9ad08ec>,)
-  >>> stmt = parsed[0]
-  >>> stmt.to_unicode()  # converting it back to unicode
-  <<< u'select * from "someschema"."mytable" where id = 1'
-  >>> # This is how the internal representation looks like:
+  >>> parsed = sqlparse.parse(sql)
+  >>> parsed
+  (<Statement 'select...' at 0x9ad08ec>,)
+
+Each item of the tuple is a single statement as identified by the above
+mentioned :meth:`~sqlparse.split` function. So let's grab the only element
+from that list and have a look at the ``tokens`` attribute.
+Sub-tokens are stored in this attribute.
+
+.. code-block:: python
+
+  >>> stmt = parsed[0]  # grab the Statement object
   >>> stmt.tokens
-  <<<
   (<DML 'select' at 0x9b63c34>,
    <Whitespace ' ' at 0x9b63e8c>,
    <Operator '*' at 0x9b63e64>,
@@ -70,16 +103,33 @@ Now, let's have a deeper look at the internals::
    <Identifier '"somes...' at 0x9b5c62c>,
    <Whitespace ' ' at 0x9b63f04>,
    <Where 'where ...' at 0x9b5caac>)
-  >>>
 
+Each object can be converted back to a string at any time:
+
+.. code-block:: python
+
+   >>> stmt.to_unicode()
+   u'select * from "someschema"."mytable" where id = 1'
+   >>> stmt.tokens[-1].to_unicode()  # or just the WHERE part
+   u'where id = 1'
 
-.. todo:: Describe general concepts
-   Why non-validating? Processing stages (tokens, groups,...), filter,
+Details of the returned objects are described in :ref:`analyze`.
 
 
 Development & Contributing
 --------------------------
 
+The source code of this module is hosted on
+`bitbucket.org <http://bitbucket.org/andialbrecht/python-sqlparse/>`_.
+
+Run
+
+.. code-block:: bash
+
+   $ hg clone http://bitbucket.org/andialbrecht/python-sqlparse/
+
+to check out the latest sources from the Mercurial repository.
+
 Please file bug reports and feature requests on the project site at
 http://code.google.com/p/python-sqlparse/issues/entry or if you have
 code to contribute upload it to http://codereview.appspot.com and