docs!

dataset/persistence/table.py

@@ -152,18 +152,19 @@ class Table(object):
         else:
             return self.table.c[order_by].asc()
 
-    def find(self, _limit=None, _step=5000, _offset=0,
+    def find(self, _limit=None, _offset=0, _step=5000,
              order_by='id', **filter):
-        """Performs a simple search on the table.
+        """Performs a simple search on the table. Simply pass keyword arguments as ``filter``.
         ::
             results = table.find(country='France')
-            # combining multiple conditions (AND)
             results = table.find(country='France', year=1980)
+
+        Using 
             # just return the first 10 rows
             results = table.find(country='France', _limit=10)
 
-        You can sort the results by single or multiple columns. For descending order
+        You can sort the results by single or multiple columns. Append a minus sign
-        please append a minus sign to the column name::
+        to the column name for descending order::
             # sort results by a column 'year'
             results = table.find(country='France', order_by='year')
             # return all rows sorted by multiple columns (by year in descending order)

docs/_themes/kr/autotoc.html

@@ -0,0 +1,25 @@
+<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+
+
+<ul class="custom-index container"></ul>
+<script type="text/javascript">
+
+$(function() {
+    var ul = $('ul.custom-index');
+    $('dl.class').each(function(i, el) {
+        var name = $('tt.descname', el).html(), id = $('dt', el).attr('id'),
+            li = $('<li><a href="#' + id + '">' + name + '</a></li>');
+        ul.append(li);
+        var ul_ = $('<ul />');
+        li.append(ul_);
+        $('dl.method', el).each(function(i, el) {
+            var name = $('tt.descname', el).html(), id = $('dt', el).attr('id');
+            ul_.append('<li><a href="#' + id + '">' + name + '</a></li>');
+        });
+    });
+
+});
+
+</script>
+
+

docs/_themes/kr/layout.html

@@ -8,9 +8,6 @@
   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
 {% endblock %}
 
-{% block sidebarlogo %}
-<iframe width="200px" scrolling="0" height="35px" frameborder="0" allowtransparency="true" src="http://ghbtns.com/github-btn.html?user=pudo&amp;repo=dataset&amp;type=watch&amp;count=true&amp;size=large"></iframe>
-{% endblock %}
 
 {% block sidebar2 %}
   {{ sidebar() }}
@@ -27,6 +24,4 @@
     <a style="position: absolute; top: 0; right: 0; border: 0;" href="https://github.com/pudo/dataset" class="github">
         <img src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"  class="github"/>
     </a>
-
-
 {%- endblock %}

docs/_themes/kr/sidebarlogo.html

@@ -0,0 +1,3 @@
+<div style="width:200px;height:140px;"></div>
+
+<iframe width="200px" scrolling="0" height="35px" frameborder="0" allowtransparency="true" src="http://ghbtns.com/github-btn.html?user=pudo&amp;repo=dataset&amp;type=watch&amp;count=true&amp;size=large"></iframe>

docs/_themes/kr/static/flasky.css_t

@@ -103,7 +103,7 @@ div.sphinxsidebar h4 {
     color: #000;
     font-size: 24px;
     font-weight: normal;
-    margin: 0 0 5px 0;
+    margin: 30px 0 5px 0;
     padding: 0;
 }
 
@@ -128,7 +128,7 @@ div.sphinxsidebar p {
 }
 
 div.sphinxsidebar ul {
-    margin: 10px 0 30px;
+    margin: 10px 0px;
     padding: 0;
     color: #000;
 }

docs/api.rst

@@ -2,15 +2,8 @@
 API documentation
 =================
 
-
-.. toctree::
-   :maxdepth: 2
-
-
-
 .. autofunction:: dataset.connect
 
-
 Database
 --------
 
@@ -18,13 +11,9 @@ Database
    :members: get_table, create_table, load_table, query
    :undoc-members:
 
-
-
 Table
 -----
 
-Using the *Table* class you can easily store and retreive data from database tables.
-
 .. autoclass:: dataset.Table
    :members:
    :undoc-members:

docs/conf.py

@@ -100,7 +100,7 @@ html_theme = 'kr'
 # further.  For a list of options available for each theme, see the
 # documentation.
 # html_theme_options = {
-#     'codebgcolor': ''
+#     'stickysidebar': "true"
 # }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -136,7 +136,11 @@ html_static_path = ['_static']
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    'index': ['sidebarlogo.html', 'sourcelink.html', 'searchbox.html'],
+    'api': ['sidebarlogo.html', 'autotoc.html', 'sourcelink.html', 'searchbox.html'],
+    '**': ['sidebarlogo.html', 'localtoc.html', 'sourcelink.html', 'searchbox.html']
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/index.rst

@@ -3,22 +3,37 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-dataset: databases for busy nerds
+dataset: databases for lazy people
-=================================
+==================================
 
-Getting the databases out of your data's way::
+.. toctree::
+   :hidden:
+
+
+Although managing data in relational database has plenty of benefits, we find them rarely being used in the typical day-to-day work with small to medium scale datasets. But why is that? Why do we see an awful lot of data stored in static files in CSV or JSON format?
+
+Because **good programmers are lazy**, and thus they tend to prefer the easiest solution they find. And managing data in a databases simply wasn't the simplest solution to store a bunch of structured data. This is where ``dataset`` steps in!
+
+Dataset is here to **take the pain out of databases**. It makes reading and writing data in databases as simple as reading and writing JSON files.
+
+In short, ::
 
    import dataset
 
-   db = dataset.connect('sqlite:///weather.db')
+   db = dataset.connect('sqlite:///database.db')
-   db['temperature'].find()
+   db['sometable'].insert(dict(name='John Doe', age=37))
+   db['sometable'].insert(dict(name='Jane Doe', age=34, gender='female'))
+
+
+Now look at `similar code, without dataset <https://gist.github.com/gka/5296492>`_.
+
 
 Features
 --------
 
-* **Automatic schema**. If a table or column is written that does not
+* **Automatic schema**: If a table or column is written that does not
   exist in the database, it will be created automatically.
-* **Upserts**. Records are either created or updated, depdending on
+* **Upserts**: Records are either created or updated, depdending on
   whether an existing version can be found.
 * **Query helpers** for simple queries such as all rows in a table or
   all distinct values across a set of columns.

docs/quickstart.rst

@@ -5,36 +5,34 @@ Quickstart
 
 Hi, welcome to the five-minute quick-start tutorial.
 
+Connecting to a database
+------------------------
+
 At first you need to import the dataset 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::
+To connect to a database you need to identify it by its `URL <http://docs.sqlalchemy.org/en/latest/core/engines.html#engine-creation-api>`_, which basically is a string of the form ``"dialect://user:password@host/dbname"``. Here are a few common examples::
 
    # connecting to a SQLite database
-   db = dataset.connect('sqlite:///factbook.db')
+   db = dataset.connect('sqlite:///mydatabase.db')
 
-   # connecting to a MySQL database
+   # connecting to a MySQL database with user and password
    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
+To store some data you need to get a reference to a table. You don't need to worry about whether the table already exists or not, since dataset will create it automatically::
-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
+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::
-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))