refactor documentation

docs/contributing.md

@@ -14,3 +14,8 @@ To run the tests, ensure that the ClickHouse server is running on <http://localh
 To see test coverage information run:
 
     bin/nosetests --with-coverage --cover-package=infi.clickhouse_orm
+
+
+---
+
+[<< System Models](system_models.md) | [Table of Contents](toc.md)

docs/field_types.md

@@ -102,3 +102,8 @@ Usage:
     db.select('SELECT created, created_date, username, name FROM $db.event', model_class=Event)
     # created_date and username will contain a default value
     db.select('SELECT * FROM $db.event', model_class=Event)
+
+
+---
+
+[<< Querysets](querysets.md) | [Table of Contents](toc.md) | [Table Engines >>](table_engines.md)

docs/index.md

@@ -9,3 +9,7 @@ Installation
 To install infi.clickhouse_orm:
 
     pip install infi.clickhouse_orm
+
+---
+
+[Table of Contents](toc.md) | [Models and Databases >>](models_and_databases.md)

docs/models_and_databases.md

@@ -170,3 +170,7 @@ You can optionally pass conditions to the query:
 
 Note that `order_by` must be chosen so that the ordering is unique, otherwise there might be inconsistencies in the pagination (such as an instance that appears on two different pages).
 
+
+---
+
+[<< Overview](index.md) | [Table of Contents](toc.md) | [Querysets >>](querysets.md)

docs/querysets.md

@@ -18,7 +18,7 @@ The `filter` and `exclude` methods are used for filtering the matching instances
     >>> qs = Person.objects_in(database)
     >>> qs = qs.filter(first_name__startswith='V').exclude(birthday__lt='2000-01-01')
     >>> qs.conditions_as_sql()
-    u"first_name LIKE 'V%' AND NOT (birthday < '2000-01-01') "
+    u"first_name LIKE 'V%' AND NOT (birthday < '2000-01-01')"
     
 It is possible to specify several fields to filter or exclude by:
 
@@ -80,7 +80,7 @@ To check if there are any matches at all, you can use any of the following equiv
 Ordering
 --------
 
-To sorting order of the results can be controlled using the `order_by` method:
+The sorting order of the results can be controlled using the `order_by` method:
 
     qs = Person.objects_in(database).order_by('last_name', 'first_name')
     
@@ -91,6 +91,11 @@ The default order is ascending. To use descending order, add a minus sign before
 Omitting Fields
 ---------------
 
-When not all model fields are needed, it is more efficient to omit them from the query. This is especially true when there are large fields that may slow the query down. Use the `only` method to specify which fields to retrieve:
+When some of the model fields aren't needed, it is more efficient to omit them from the query. This is especially true when there are large fields that may slow the query down. Use the `only` method to specify which fields to retrieve:
 
     qs = Person.objects_in(database).only('first_name', 'birthday')
+
+
+---
+
+[<< Models and Databases](models_and_databases.md) | [Table of Contents](toc.md) | [Field Types >>](field_types.md)

docs/schema_migrations.md

@@ -57,4 +57,9 @@ To migrate a database, create a `Database` instance and call its `migrate` metho
 
     Database('analytics_db').migrate('analytics.analytics_migrations')
 
-Note that you may have more than one migrations package.
+Note that you may have more than one migrations package.
+
+
+---
+
+[<< Table Engines](table_engines.md) | [Table of Contents](toc.md) | [System Models >>](system_models.md)

docs/system_models.md

@@ -1,4 +1,4 @@
-System models
+System Models
 =============
 
 [Clickhouse docs](https://clickhouse.yandex/reference_en.html#System%20tables).
@@ -11,7 +11,7 @@ Currently the following system models are supported:
 | ------------ | -------------- | ---------------------------------------------------
 | SystemPart   | system.parts   | Gives methods to work with partitions. See below.
 
-Partitions and parts
+Partitions and Parts
 --------------------
 
 [ClickHouse docs](https://clickhouse.yandex/reference_en.html#Manipulations%20with%20partitions%20and%20parts).
@@ -40,3 +40,8 @@ Usage example:
         partitions[0].drop()  # Dropped partition
 
 `Note`: system.parts stores information for all databases. To be correct, SystemPart model was designed to receive only parts belonging to the given database instance.
+
+
+---
+
+[<< Schema Migrations](schema_migrations.md) | [Table of Contents](toc.md) | [Contributing >>](contributing.md)

docs/table_engines.md

@@ -56,3 +56,8 @@ Any of the above engines can be converted to a replicated engine (e.g. `Replicat
     engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate'),
                                replica_table_path='/clickhouse/tables/{layer}-{shard}/hits',
                                replica_name='{replica}')
+
+
+---
+
+[<< Field Types](field_types.md) | [Table of Contents](toc.md) | [Schema Migrations >>](schema_migrations.md)

docs/toc.md

@@ -1,3 +1,5 @@
+Table of Contents
+=================
 
    * [Overview](index.md#overview)
       * [Installation](index.md#installation)
@@ -13,6 +15,13 @@
       * [Counting](models_and_databases.md#counting)
       * [Pagination](models_and_databases.md#pagination)
 
+   * [Querysets](querysets.md#querysets)
+      * [Filtering](querysets.md#filtering)
+         * [Using the in Operator](querysets.md#using-the-in-operator)
+      * [Counting and Checking Existence](querysets.md#counting-and-checking-existence)
+      * [Ordering](querysets.md#ordering)
+      * [Omitting Fields](querysets.md#omitting-fields)
+
    * [Field Types](field_types.md#field-types)
       * [DateTimeField and Time Zones](field_types.md#datetimefield-and-time-zones)
       * [Working with enum fields](field_types.md#working-with-enum-fields)
@@ -27,7 +36,7 @@
       * [Writing Migrations](schema_migrations.md#writing-migrations)
       * [Running Migrations](schema_migrations.md#running-migrations)
 
-   * [System models](system_models.md#system-models)
+   * [System Models](system_models.md#system-models)
-      * [Partitions and parts](system_models.md#partitions-and-parts)
+      * [Partitions and Parts](system_models.md#partitions-and-parts)
 
    * [Contributing](contributing.md#contributing)

scripts/README.md

@@ -1,5 +1,18 @@
 This directory contains various scripts for use while developing.
 
+generate_toc
+------------
+Generates the table of contents (toc.md)
+Usage:
+    cd docs
+    ../scripts/generate_toc.sh
+
+
+gh-md-toc
+---------
+Used by generate_toc.
+
+
 docs2html
 ---------
 Converts markdown docs to html for preview. Requires Pandoc.
@@ -9,11 +22,6 @@ Usage:
     ../scripts/docs2html.sh
 
 
-gh-md-toc
----------
-Used by docs2html to generate the table of contents.
-
-
 test_python3
 ------------
 Creates a Python 3 virtualenv, clones the project into it, and runs the tests.

scripts/docs2html.sh

@@ -1,18 +1,6 @@
 
 mkdir -p ../htmldocs
 
-echo "Generating table of contents"
-../scripts/gh-md-toc \
-    index.md \
-    models_and_databases.md \
-    querysets.md \
-    field_types.md \
-    table_engines.md \
-    schema_migrations.md \
-    system_models.md \
-    contributing.md \
-    > toc.md
-
 find ./ -iname "*.md" -type f -exec sh -c 'echo "Converting ${0}"; pandoc "${0}" -s -o "../htmldocs/${0%.md}.html"' {} \;
 
 echo "Fixing links"

scripts/generate_toc.sh

@@ -0,0 +1,13 @@
+echo "Table of Contents" > toc.md
+echo "=================" >> toc.md
+
+../scripts/gh-md-toc \
+    index.md \
+    models_and_databases.md \
+    querysets.md \
+    field_types.md \
+    table_engines.md \
+    schema_migrations.md \
+    system_models.md \
+    contributing.md \
+    >> toc.md