Docs: updated README.rst file (#563)

Author: mf2199

README.rst

@@ -5,20 +5,35 @@ ORM plugin for using Cloud Spanner as a `database backend
 <https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__
 for Django.
 
+How it works
+------------
+
+Overall design
+~~~~~~~~~~~~~~
+
+.. figure:: ./assets/overview.png
+   :alt:
+
+Internals
+~~~~~~~~~
+
+.. figure:: ./assets/internals.png
+   :alt:
+
 
 Installation
 ------------
 
-To use this library you'll need a Google Cloud Platform project with the Cloud
-Spanner API enabled. See the `Cloud Spanner Python client docs
+Using this library requires a Google Cloud Platform project with the Cloud
+Spanner API enabled. See the Spanner Python client `documentation
 <https://github.com/googleapis/python-spanner/#quick-start>`__ for details.
 
-Use the version of ``django-google-spanner`` that corresponds to your version
+The version of ``django-google-spanner`` must correspond to your version
 of Django.  For example, ``django-google-spanner`` 2.2.x works with Django
-2.2.y. (This is the only supported version at this time.)
+2.2.y (Note: this is the only supported version at this time).
 
-The minor release number of Django doesn't correspond to the minor release
-number of ``django-google-spanner``. Use the latest minor release of each.
+The minor release numbers of Django may not correspond to the minor release
+numbers of ``django-google-spanner``. Use the latest minor release of each.
 
 To install from PyPI:
 
@@ -36,15 +51,14 @@ To install from source:
     pip3 install -e .
 
 
-Usage
------
+Configuring ``settings.py``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After `installation <#Installation>`__, you'll need to edit your Django
-``settings.py`` file:
+After `installation <#Installation>`__, you'll have to update your Django
+``settings.py`` file as follows.
 
 -  Add ``django_spanner`` as the very first entry in the ``INSTALLED_APPS``
-   setting
-
+   settings:
 
    .. code:: python
 
@@ -53,49 +67,43 @@ After `installation <#Installation>`__, you'll need to edit your Django
            ...
        ]
 
--  Edit the ``DATABASES`` setting to point to an EXISTING database
-
-Format
-~~~~~~
+-  Edit the ``DATABASES`` settings to point to an EXISTING database, as shown in the following example:
 
-.. code:: python
-
-    DATABASES = {
-        'default': {
-            'ENGINE': 'django_spanner',
-            'PROJECT': '<project_id>',
-            'INSTANCE': '<instance_id>',
-            'NAME': '<database_name>',
-            # Only include this if you need to specify where to retrieve the
-            # service account JSON for the credentials to connect to Cloud Spanner.
-            'OPTIONS': {
-                'credentials_uri': '<credentials_uri>',
-            },
-        },
-    }
-
-Database configurations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: python
-
-    DATABASES = {
-        'default': {
-            'ENGINE': 'django_spanner',
-            'PROJECT': 'appdev-soda-spanner-staging', # Or the GCP project-id
-            'INSTANCE': 'django-dev1', # Or the Cloud Spanner instance
-            'NAME': 'db1', # Or the Cloud Spanner database to use
-        }
-    }
+   .. code:: python
 
-Execute a query
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+       DATABASES = {
+           'default': {
+               'ENGINE': 'django_spanner',
+               'PROJECT': '<GCP_project_id>',
+               'INSTANCE': '<instance_id>',
+               'NAME': '<database_name>',
+           }
+       }
+
+-   In order to retrieve the Cloud Spanner credentials from a JSON file, the ``credentials_uri`` parameter can also be supplied in the ``OPTIONS`` field:
+
+    .. code:: python
+
+       DATABASES = {
+           'default': {
+               'ENGINE': 'django_spanner',
+               'PROJECT': '<GCP_project_id>',
+               'INSTANCE': '<instance_id>',
+               'NAME': '<database_name>',
+               'OPTIONS': {
+                   'credentials_uri': '<credentials_uri>',
+               },
+           },
+       }
+
+Executing a query
+~~~~~~~~~~~~~~~~~
 
 .. code:: python
 
     from google.cloud.spanner_dbapi import connect
 
-    connection = connect("instance-id", "database-id")
+    connection = connect('<instance_id>', '<database_id>')
     cursor = connection.cursor()
 
     cursor.execute(
@@ -107,16 +115,8 @@ Execute a query
     results = cur.fetchall()
 
 
-Limitations
------------
-
-Transaction management isn't supported
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``django-google-spanner`` always works in ``autocommit`` mode, which is
-Django's default behavior even for backends that support manual transaction
-management. Transactions cannot be controlled manually with calls like
-``django.db.transaction.atomic()``.
+Current limitations
+-------------------
 
 ``AutoField`` generates random IDs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -139,34 +139,34 @@ these IDs are not monotonically increasing. This means that sorting
 models by ID isn't guaranteed to return them in the order in which they
 were created.
 
-``ForeignKey`` constraints aren't created
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``ForeignKey`` constraints aren't created (`#313 <https://github.com/googleapis/python-spanner-django/issues/313>`__)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Spanner doesn't support ``ON DELETE CASCADE`` when creating foreign-key
-constraints so ``django-google-spanner`` `doesn't support foreign key
-constraints
-<https://github.com/googleapis/python-spanner-django/issues/313>`__.
+Spanner does not support ``ON DELETE CASCADE`` when creating foreign-key
+constraints, so this is not supported in ``django-google-spanner``.
 
 Check constraints aren't supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Spanner doesn't support ``CHECK`` constraints so one isn't created for
+Spanner does not support ``CHECK`` constraints so one isn't created for
 `PositiveIntegerField
 <https://docs.djangoproject.com/en/stable/ref/models/fields/#positiveintegerfield>`__
 and `CheckConstraint
 <https://docs.djangoproject.com/en/stable/ref/models/constraints/#checkconstraint>`__
 can't be used.
 
-``DecimalField`` isn't supported
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+No native support for ``DecimalField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Spanner doesn't support a NUMERIC data type that allows storing high
-precision decimal values without the possibility of data loss.
+Spanner's support for `Decimal <https://www.python.org/dev/peps/pep-0327/>`__
+types is limited to
+`NUMERIC <https://cloud.google.com/spanner/docs/data-types#numeric_types>`__
+precision. Higher-precision values can be stored as strings instead.
 
 ``Variance`` and ``StdDev`` database functions aren't supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Spanner doesn't support these functions.
+Spanner does not support these functions.
 
 ``Meta.order_with_respect_to`` model option isn't supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -177,7 +177,7 @@ This feature uses a column name that starts with an underscore
 Random ``QuerySet`` ordering isn't supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Spanner doesn't support it. For example:
+Spanner does not support it and will throw an exception. For example:
 
 ::
 
@@ -189,13 +189,11 @@ Spanner doesn't support it. For example:
 Schema migrations
 ~~~~~~~~~~~~~~~~~
 
-Spanner has some limitations on schema changes which you must respect:
+There are some limitations on schema changes to consider:
 
--  Renaming tables and columns isn't supported.
--  A column's type can't be changed.
+-  No support for renaming tables and columns;
+-  A column's type can't be changed;
 -  A table's primary key can't be altered.
--  Migrations aren't atomic since ``django-google-spanner`` doesn't support
-   transactions.
 
 ``DurationField`` arithmetic doesn't work with ``DateField`` values (`#253 <https://github.com/googleapis/python-spanner-django/issues/253>`__)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -207,20 +205,23 @@ the column type:
    or ``TIMESTAMP_SUB``
 -  ``DATE`` columns (``DateField``) require ``DATE_ADD`` or ``DATE_SUB``
 
-Django doesn't provide a way to determine which database function to
-use. ``DatabaseOperations.combine_duration_expression()`` arbitrary uses
+Django does not provide ways to determine which database function to
+use. ``DatabaseOperations.combine_duration_expression()`` arbitrarily uses
 ``TIMESTAMP_ADD`` and ``TIMESTAMP_SUB``. Therefore, if you use a
-``DateField`` in a ``DurationField`` expression, you'll see an error
-like: "No matching signature for function TIMESTAMP\_ADD for argument
-types: DATE, INTERVAL INT64 DATE\_TIME\_PART."
+``DateField`` in a ``DurationField`` expression, you'll likely see an error
+such as:
 
-Computations that yield FLOAT64 values can't be assigned to INT64 columns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+::
 
-Spanner `doesn't support
-this <https://github.com/googleapis/python-spanner-django/issues/331>`__.
+    "No matching signature for function TIMESTAMP\_ADD for argument types:
+    DATE, INTERVAL INT64 DATE\_TIME\_PART."
 
-For example, if ``integer`` is ``IntegerField``:
+Computations that yield FLOAT64 values cannot be assigned to INT64 columns
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Spanner does not support this (`#331
+<https://github.com/googleapis/python-spanner-django/issues/331>`__) and will
+throw an error:
 
 ::
 
@@ -233,26 +234,11 @@ For example, if ``integer`` is ``IntegerField``:
 Addition with null values crash
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For example:
+Additions cannot include ``None`` values. For example:
 
 ::
 
     >>> Book.objects.annotate(adjusted_rating=F('rating') + None)
     ...
     google.api_core.exceptions.InvalidArgument: 400 Operands of + cannot be literal
     NULL ...
-
-How it works
-------------
-
-Overall design
-~~~~~~~~~~~~~~
-
-.. figure:: ./assets/overview.png
-   :alt:
-
-Internals
-~~~~~~~~~
-
-.. figure:: ./assets/internals.png
-   :alt:

docs/api-reference.rst

@@ -1,6 +1,6 @@
 API Reference
 =============
 
-The following classes and methods constitute the Spanner DB API connection.
+The following classes and methods constitute the Django Spanner API.
 
 [this page is under construction]

docs/connection-usage.rst

@@ -1,13 +1,5 @@
 .. include:: README.rst
 
-Usage Documentation
--------------------
-.. toctree::
-  :maxdepth: 1
-  :titlesonly:
-
-  connection-usage
-
 API Documentation
 -----------------
 .. toctree::