PLAT-245 -- Amend and finish up docs.

Author: gianchub

README.rst

@@ -0,0 +1,9 @@
+SqlAlchemy Diff
+===============
+
+.. pull-quote::
+
+    Verify that your alembic migrations are valid and equivalent to your
+    models.
+
+Documentation here: (link to read the docs)

docs/source/full_example.rst

@@ -0,0 +1,23 @@
+.. _full_example:
+
+A full comparison PyTest Example
+================================
+
+
+Let's assume we have the following models:
+
+``# models_left.py``
+
+.. literalinclude:: ../testing/models_left.py
+
+And these:
+
+``# models_right.py``
+
+.. literalinclude:: ../testing/models_right.py
+
+
+This is how you could write a complete test suite for them:
+
+
+.. literalinclude:: ../testing/test_example.py

docs/source/index.rst

@@ -0,0 +1,117 @@
+Alembic Verify
+==============
+
+.. pull-quote::
+
+    Verify that your alembic migrations are valid and equivalent to your
+    models.
+
+
+PyTest Example
+--------------
+
+This is how you can use the library to verify that two schemas are
+the same:
+
+.. literalinclude:: ../testing/test_example.py
+    :lines: 6,8,9,13-22
+
+
+You can also make sure that two schemas are different:
+
+.. literalinclude:: ../testing/test_example.py
+    :lines: 25-33
+
+
+If your test fails, you can dump the errors to a file by just adding
+the following line of code:
+
+.. code-block:: Python
+
+    result.dump_errors()
+
+
+That will dump the errors dict to a JSON file that looks like this:
+
+.. code-block:: JSON
+
+    {
+        'tables': {
+            'left_only': ['addresses'],
+            'right_only': ['roles']
+        },
+        'tables_data': {
+            'employees': {
+                'columns': {
+                    'left_only': [
+                        {
+                            'default': None,
+                            'name': 'favourite_meal',
+                            'nullable': False,
+                            'type': "ENUM('meat','vegan')"
+                        }
+                    ],
+                    'right_only': [
+                        {
+                            'autoincrement': False,
+                            'default': None,
+                            'name': 'role_id',
+                            'nullable': False,
+                            'type': 'INTEGER(11)'
+                        },
+                        {
+                            'autoincrement': False,
+                            'default': None,
+                            'name': 'number_of_pets',
+                            'nullable': False,
+                            'type': 'INTEGER(11)'
+                        },
+                    ]
+                },
+                'foreign_keys': { ... },
+                'primary_keys': { ... },
+                'indexes': { .. }
+            },
+            'phone_numbers': { ... }
+        },
+        'uris': {
+            'left': "your left URI",
+            'right': "your right URI",
+        }
+    }
+
+
+Using unittest
+--------------
+
+If you prefer, you can use unittest:
+
+.. literalinclude:: ../testing/test_unittest.py
+    :lines: 2-47
+
+
+Features
+--------
+
+Currently the library can detect the following differences:
+
+- Differences in **Tables**
+- Differences in **Primary Keys** for a common table
+- Differences in **Foreign Keys** for a common table
+- Differences in **Indexes** for a common table
+- Differences in **Columns** for a common table
+
+
+Installation
+------------
+
+.. code-block:: bash
+
+    $ pip install alembic-verify
+
+
+Full Example
+------------
+
+:ref:`Here <full_example>` you can find a full example on how to test
+two databases which are different.

docs/testing/test_example.py

@@ -188,7 +188,7 @@ def test_errors_dict_catches_all_differences(uri_left, uri_right):
         },
         'uris': {
             'left': uri_left,
-            'right': uri_right
+            'right': uri_right,
         }
     }