documentation!

docs/api.rst

@@ -1,5 +1,7 @@
 
-Contents:
+API documentation
+=================
+
 
 .. toctree::
    :maxdepth: 2
@@ -10,13 +12,7 @@ Contents:
 
 
 Database
-========
+--------
-
-A Database is a simple wrapper around SQLAlchemy engines. Most of the time you want to use it to get instances to tables using *get_table* or the short-hand dict syntax::
-
-   # both statements return the same table
-   table = db['population']
-   table = db.get_table('population')
 
 .. autoclass:: dataset.Database
    :members: get_table, create_table, load_table, query
@@ -25,7 +21,7 @@ A Database is a simple wrapper around SQLAlchemy engines. Most of the time you w
 
 
 Table
-=====
+-----
 
 Using the *Table* class you can easily store and retreive data from database tables.
 

docs/index.rst

@@ -6,68 +6,13 @@
 Welcome to dataset's documentation!
 ===================================
 
-Contents:
+Getting the databases out of your data's way.
 
 .. toctree::
    :maxdepth: 2
 
-
+* `Learn how to use dataset in five minutes <quickstart>`_
-
+* `Browse the complete API docs <api>`_
-Quick-start
-===========
-
-At first you need to import the package :). To connect to a database you need to identify it using
-what is called an engine url. Here are a few examples::
-
-   import dataset
-
-   # connecting to a SQLite database
-   db = dataset.connect('sqlite:///factbook.db')
-
-   # connecting to a MySQL database
-   db = dataset.connect('mysql:///')
-
-
-Storing data
-------------
-Storing data in a table is as simple. **dataset** will automatically create the columns, if they don't exist yet::
-
-   table.insert(dict(country='China', year=2012, population=1354040000))
-
-
-Reading data from tables
-------------------------
-
-Checking::
-
-   table = db['population']
-
-   # Let's grab a list of all items/rows/entries in the table:
-   table.all()
-
-   table.distinct()
-
-Searching for specific entries::
-
-   # Returns the first item where the column country equals 'China'
-   table.find_one(country='China')
-
-   # Returns all items
-   table.find(country='China')
-
-
-
-
-You can add additional columns at any time::
-
-   table.insert(dict(country='US', year=2013, population=315591999, source='http://www.census.gov'))
-
-Updating existing entries::
-
-   table.update(dict(country='China', year=2012, population=1354040001), ['country', 'year'])
-
-
-
 
 
 

docs/quickstart.rst

@@ -0,0 +1,75 @@
+
+Quick-start
+===========
+
+
+.. toctree::
+   :maxdepth: 2
+
+Hi, welcome to the five-minute quick-start tutorial.
+
+At first you need to import the package :).::
+
+   import dataset
+
+To connect to a database you need to identify it using what is called an engine url. Here are a few examples::
+
+   # connecting to a SQLite database
+   db = dataset.connect('sqlite:///factbook.db')
+
+   # connecting to a MySQL database
+   db = dataset.connect('mysql://user:password@localhost/mydatabase')
+
+   # connecting to a PostgreSQL database
+   db = dataset.connect('postgresql://scott:tiger@localhost:5432/mydatabase')
+
+If you want to learn more about how to connect to various databases, have a look at the `SQLAlchemy documentation`_.
+
+.. _SQLAlchemy documentation: http://docs.sqlalchemy.org/en/latest/core/engines.html#engine-creation-api
+
+Storing data
+------------
+
+At first you need to get a reference to the table in which you want to store your data. You don't
+need to worry about whether the table already exists or not, since dataset will create it automatically::
+
+   # get a reference to the table 'person'
+   table = db['person']
+
+Now storing data in a table is a matter of a single function call. Just pass a `dict`_ to *insert*. Note
+that you don't need to create the columns *name* and *age* – dataset will do this automatically::
+
+   # Insert a new record.
+   table.insert(dict(name='John Doe', age=46))
+
+   # dataset will create "missing" columns any time you insert a dict with an unknown key
+   table.insert(dict(name='Jane Doe', age=37, gender='female'))
+
+   # If you need to insert many items at once, you can speed up things by using insert_many:
+   table.insert_many(list_of_persons)
+
+.. _dict: http://docs.python.org/2/library/stdtypes.html#dict
+
+Updating existing entries is easy, too::
+
+   table.update(dict(name='John Doe', age=47), ['name'])
+
+Reading data from tables
+------------------------
+
+Checking::
+
+   table = db['population']
+
+   # Let's grab a list of all items/rows/entries in the table:
+   table.all()
+
+   table.distinct()
+
+Searching for specific entries::
+
+   # Returns the first item where the column country equals 'China'
+   table.find_one(country='China')
+
+   # Returns all items
+   table.find(country='China')