docs: Adding documentation for GA (#665)

* changes to docs for sphinx

* remvoing warnings

* adding sample code

* linting

* modifying import settings

* settings changes

* line accidently deleted in creation.py

* lint_setup_py test

* adding new lines and making changes to read me

Co-authored-by: Vikash Singh <[email protected]>

Author: asthamohta

README.rst

@@ -1,6 +1,37 @@
 Cloud Spanner support for Django
 ================================
 
+`Cloud Spanner`_ is the world's first fully managed relational database service
+to offer both strong consistency and horizontal scalability for
+mission-critical online transaction processing (OLTP) applications. With Cloud
+Spanner you enjoy all the traditional benefits of a relational database; but
+unlike any other relational database service, Cloud Spanner scales horizontally
+to hundreds or thousands of servers to handle the biggest transactional
+workloads.
+
+
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. _Cloud Spanner: https://cloud.google.com/spanner/
+.. _Client Library Documentation: https://googleapis.dev/python/django-google-spanner/latest/index.html
+.. _Product Documentation:  https://cloud.google.com/spanner/docs
+
+Quick Start
+-----------
+
+In order to use this library, you first need to go through the following steps:
+
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Spanner API.`_
+4. `Setup Authentication.`_
+
+.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
+.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
+.. _Enable the Google Cloud Spanner API.:  https://cloud.google.com/spanner
+.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+
 This package provides a `3rd-party database backend
 <https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__
 for using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django
@@ -11,10 +42,40 @@ under the hood.
 Installation
 ------------
 
-To use this library, you'll need a Google Cloud Platform project with the Cloud
-Spanner API enabled. For details on enabling the API and authenticating with
-GCP, see the `Cloud Spanner Python client library quickstart guide
-<https://github.com/googleapis/python-spanner/#quick-start>`__.
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python and Django environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
+
+With `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
+
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
+
+
+Mac/Linux
+~~~~~~~~~
+
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install python-spanner-django
+    <your-env>/bin/pip install google-cloud-spanner
+
+
+Windows
+~~~~~~~
+
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install python-spanner-django
+    <your-env>\Scripts\pip.exe install google-cloud-spanner
+
 
 Supported versions
 ~~~~~~~~~~~~~~~~~~
@@ -93,52 +154,104 @@ configured:
        }
 
 
+Set credentials and project environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You'll need to download a service account JSON key file and point to it using an environment variable:
+
+.. code:: shell
+
+    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
+    export GOOGLE_CLOUD_PROJECT=gcloud_project
+
+
+Apply the migrations
+~~~~~~~~~~~~~~~~~~~~
+
+Please run:
+
+.. code:: shell
+
+    $ python3 manage.py migrate
+
+and that'll take a while to run. After this you should be able to see the tables and indices created in your Cloud Spanner console.
+
+Now run your server
+~~~~~~~~~~~~~~~~~~~
+After those migrations are completed, that will be all. Please continue on with the guides.
+
+Create an Django admin user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+First you’ll need to create a user who can login to the admin site. Run the following command:
+
+.. code:: shell
+
+    $ python3 manage.py createsuperuser
+
+which will then produce a prompt which will allow you to create your super user
+
+.. code:: shell
+
+    Username: admin
+    Email address: [email protected]
+    Password: **********
+    Password (again): **********
+    Superuser created successfully.
+
+
+Login as admin
+~~~~~~~~~~~~~~
+Let’s run the server
+
+.. code:: shell
+
+    python3 manage.py runserver
+
+Then visit http://127.0.0.1:8000/admin/
+
+Create and register your first model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please follow the guides in https://docs.djangoproject.com/en/2.2/intro/tutorial02/#creating-models
+to create and register the model to the Django’s automatically-generated admin site.
+
 How it works
 ------------
 
 Overall design
 ~~~~~~~~~~~~~~
 
-.. figure:: ./assets/overview.png
-   :alt:
+.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/master/assets/overview.png
+   :alt: "Overall Design"
 
 Internals
 ~~~~~~~~~
 
-.. figure:: ./assets/internals.png
-   :alt:
-
+.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/master/assets/internals.png
+   :alt: "Internals"
 
 
 Executing a query
 ~~~~~~~~~~~~~~~~~
 
-.. code:: python
-
-    from google.cloud.spanner_dbapi import connect
+Here is an example of how to add a row for Model Author, save it and later query it using Django
 
-    connection = connect('<instance_id>', '<database_id>')
-    cursor = connection.cursor()
-
-    cursor.execute(
-        "SELECT *"
-        "FROM Singers"
-        "WHERE SingerId = 15"
-    )
+.. code:: shell
 
-    results = cursor.fetchall()
+    >>> author_kent = Author( first_name="Arthur", last_name="Kent", rating=Decimal("4.1"),)
+    >>> author_kent.save()
+    >>> qs1 = Author.objects.all().values("first_name", "last_name")
 
 
-Contributing
-------------
+HOW TO CONTRIBUTE
+-----------------
 
 Contributions to this library are always welcome and highly encouraged.
 
-See [CONTRIBUTING][contributing] for more information on how to get started.
+See `CONTRIBUTING <https://github.com/googleapis/python-spanner-django/blob/master/CONTRIBUTING.md>`_ for more information on how to get started.
 
 Please note that this project is released with a Contributor Code of Conduct.
-By participating in this project you agree to abide by its terms. See the `Code
-of Conduct <code-of-conduct.md>`_ for more information.
+By participating in this project you agree to abide by its terms. See the `Code 
+of Conduct <https://github.com/googleapis/python-spanner-django/blob/master/CODE_OF_CONDUCT.md>`_ for more information.
 
 Current limitations
 -------------------

django_spanner/functions.py

@@ -38,7 +38,7 @@ def cast(self, compiler, connection, **extra_context):
     A method to extend Django Cast class. Cast SQL query for given
     parameters.
 
-    :type self: :class:`~django.db.models.functions.comparison.Cast`
+    :type self: :class:`~django.db.models.functions.Cast`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -71,7 +71,7 @@ def chr_(self, compiler, connection, **extra_context):
     A method to extend Django Chr class. Returns a SQL query where the code
     points are displayed as a string.
 
-    :type self: :class:`~django.db.models.functions.text.Chr`
+    :type self: :class:`~django.db.models.functions.Chr`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -101,7 +101,7 @@ def concatpair(self, compiler, connection, **extra_context):
     A method to extend Django ConcatPair class. Concatenates a SQL query
     into the sequence of :class:`IfNull` objects.
 
-    :type self: :class:`~django.db.models.functions.text.ConcatPair`
+    :type self: :class:`~django.db.models.functions.ConcatPair`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -132,7 +132,7 @@ def cot(self, compiler, connection, **extra_context):
     A method to extend Django Cot class. Returns a SQL query of calculated
     trigonometric cotangent function.
 
-    :type self: :class:`~django.db.models.functions.math.Cot`
+    :type self: :class:`~django.db.models.functions.Cot`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -162,7 +162,7 @@ def degrees(self, compiler, connection, **extra_context):
     A method to extend Django Degress class. Returns a SQL query of the
     angle converted to degrees.
 
-    :type self: :class:`~django.db.models.functions.math.Degrees`
+    :type self: :class:`~django.db.models.functions.Degrees`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -190,8 +190,8 @@ def degrees(self, compiler, connection, **extra_context):
 def left_and_right(self, compiler, connection, **extra_context):
     """A method to extend Django Left and Right classes.
 
-    :type self: :class:`~django.db.models.functions.text.Left` or
-                :class:`~django.db.models.functions.text.Right`
+    :type self: :class:`~django.db.models.functions.Left` or
+                :class:`~django.db.models.functions.Right`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -216,7 +216,7 @@ def log(self, compiler, connection, **extra_context):
     A method to extend Django Log class. Returns a SQL query of calculated
     logarithm.
 
-    :type self: :class:`~django.db.models.functions.math.Log`
+    :type self: :class:`~django.db.models.functions.Log`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -245,7 +245,7 @@ def ord_(self, compiler, connection, **extra_context):
     A method to extend Django Ord class. Returns a SQL query of the
     expression converted to ord.
 
-    :type self: :class:`~django.db.models.functions.text.Ord`
+    :type self: :class:`~django.db.models.functions.Ord`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -275,7 +275,7 @@ def pi(self, compiler, connection, **extra_context):
     A method to extend Django Pi class. Returns a SQL query of the Pi
     constant.
 
-    :type self: :class:`~django.db.models.functions.math.Pi`
+    :type self: :class:`~django.db.models.functions.Pi`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -302,7 +302,7 @@ def radians(self, compiler, connection, **extra_context):
     A method to extend Django Radians class. Returns a SQL query of the
     angle converted to radians.
 
-    :type self: :class:`~django.db.models.functions.math.Radians`
+    :type self: :class:`~django.db.models.functions.Radians`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -332,7 +332,7 @@ def strindex(self, compiler, connection, **extra_context):
     A method to extend Django StrIndex class. Returns a SQL query of the
     string position.
 
-    :type self: :class:`~django.db.models.functions.text.StrIndex`
+    :type self: :class:`~django.db.models.functions.StrIndex`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -359,7 +359,7 @@ def substr(self, compiler, connection, **extra_context):
     A method to extend Django Substr class. Returns a SQL query of a
     substring.
 
-    :type self: :class:`~django.db.models.functions.text.Substr`
+    :type self: :class:`~django.db.models.functions.Substr`
     :param self: the instance of the class that owns this method.
 
     :type compiler: :class:`~django_spanner.compiler.SQLCompilerst`

docs/api-reference.rst

@@ -7,3 +7,12 @@ The following classes and methods constitute the Django Spanner API.
     :maxdepth: 1
 
     schema-api
+    base-api
+    compiler-api
+    expressions-api
+    functions-api
+    introspection-api
+    lookups-api
+    utils-api
+    creation-api
+    operations-api

docs/base-api.rst

@@ -0,0 +1,7 @@
+Base API
+=====================
+
+.. automodule:: django_spanner.base
+  :members:
+  :inherited-members:
+  

docs/compiler-api.rst

@@ -0,0 +1,7 @@
+Compiler API
+=====================
+
+.. automodule:: django_spanner.compiler
+  :members:
+  :inherited-members:
+  

docs/conf.py

@@ -19,7 +19,11 @@
 import sys
 import os
 import shlex
+import django
 
+sys.path.insert(0, os.path.abspath(".."))
+os.environ["DJANGO_SETTINGS_MODULE"] = "tests.settings"
+django.setup()
 # If extensions (or modules to document with autodoc) are in another directory,
 # add this directory to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.

docs/creation-api.rst

@@ -0,0 +1,7 @@
+Creation API
+=====================
+
+.. automodule:: django_spanner.creation
+  :members:
+  :inherited-members:
+  

docs/expressions-api.rst

@@ -0,0 +1,7 @@
+Expressions API
+=====================
+
+.. automodule:: django_spanner.expressions
+  :members:
+  :inherited-members:
+  

docs/functions-api.rst

@@ -0,0 +1,7 @@
+Functions API
+=====================
+
+.. automodule:: django_spanner.functions
+  :members:
+  :inherited-members:
+  

docs/index.rst

@@ -6,7 +6,7 @@ Usage Documentation
   :maxdepth: 1
   :titlesonly:
 
-  schema-usage
+  samples
 
 API Documentation
 -----------------