Completed this phase of updates to sphinx docs

Author: emiliom

docs/source/contribute.rst

@@ -42,7 +42,7 @@ The latest development version is found in the ``development`` branch of the git
        pip install git+https://github.com/ODM2/ODM2PythonAPI.git@development#egg=odm2api
 
 
-Contribute to Documentation
+Contribute to documentation
 ----------------------------------
 
 This guide is a reference on how to contribute to ODM2 Documentation effort

docs/source/getstarted.rst

@@ -2,11 +2,11 @@ Get Started
 ============
 
 
-Install the latest release from a conda package
-------------------------------------------------
+Install the latest release with conda
+-------------------------------------
 
 conda
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^
 
 The easiest and most reliable way to install the ODM2 Python API
 (``odm2api``) is using the `Conda package management
@@ -29,10 +29,10 @@ changes have been made to support Python 3.x, but they haven't been
 tested thoroughly.
 
 Install the conda package
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The `latest release <https://github.com/ODM2/ODM2PythonAPI/releases>`_ is available
-on the `conda-forge anaconda.org channel <https://anaconda.org/conda-forge/odm2api>`_
+as a package on the `conda-forge anaconda.org channel <https://anaconda.org/conda-forge/odm2api>`_
 for all major OS platforms (linux, OS X, win32/win64). To install it on
 an existing conda environment:
 
@@ -51,17 +51,63 @@ To create a new environment "myenv" with the ``odm2api`` package:
 
 
 Code examples
-----------------------------------------------
+-------------
 
+Connecting to an ODM2 database
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Connect to an ODM2 database and open the connection for reading.
+
+.. code-block:: python
+
+    from odm2api.ODMconnection import dbconnection
+    import odm2api.services.readService as odm2rs
+
+    # A SQLite file-based connection
+    session_factory = dbconnection.createConnection('sqlite', 
+                                                    '/myfilepath/odm2db.sqlite')
+    read = odm2rs.ReadODM2(session_factory)
+
+    # A connection to a server-based database system
+    db_credentials = {
+        'address': 'ip-or-domainname',
+        'db': 'dbname',
+        'user': 'dbuser',
+        'password': 'password'
+    }
+    session_factory = dbconnection.createConnection('postgresql',
+                                                    **db_credentials)
+    read = odm2rs.ReadODM2(session_factory)
+
+
+Updating an entity (table)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `update services <https://github.com/ODM2/ODM2PythonAPI/blob/master/odm2api/services/updateService.py>`_ 
+have not been fleshed out at this time, for the most part. However, updates can be easily
+accomplished by reusing the connection setup at the start of an odm2api session, 
+then constructing and issuing a direct ``SQL UPDATE`` statement, like this:
+
+.. code-block:: python
+
+    from odm2api.ODMconnection import dbconnection
+
+    session_factory = dbconnection.createConnection('postgresql', 
+                                                    **db_cred)
+    DBSession = session_factory.getSession()
+
+    sq_str = " UPDATE mytable SET variablecode = 'xyz' WHERE variablecode = 'abc' "
+    DBSession.execute(sql_str)
+    DBSession.commit()
 
 
 Sample Jupyter notebooks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------
 
-Also mention the associated SQLite ODM2 databases. And the conda environment file.
+These two notebooks are complete, extended examples that illustrate reading from ODM2 databases and using the resulting data and metadata. They use SQLite ODM2 file databases that can be `downloaded here <https://github.com/ODM2/ODM2PythonAPI/tree/master/Examples/data>`_. 
+A conda environment to run these notebooks can be created with the conda environment file 
+`clientenvironment.yml <https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/clientenvironment.yml>`_.
 
 1. `WaterQualityMeasurements_RetrieveVisualize.ipynb <https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/WaterQualityMeasurements_RetrieveVisualize.ipynb>`_
 
 2. `TimeSeries_RetrieveVisualize.ipynb <https://github.com/ODM2/ODM2PythonAPI/blob/master/Examples/TimeSeries_RetrieveVisualize.ipynb>`_
-

docs/source/index.rst

@@ -13,8 +13,8 @@ A Python-based application programmer's interface for the `Observations Data Mod
    contribute
    credits
 
-Indices
-=======
+Indices and Search
+==================
 
 .. toctree::
    :maxdepth: 2

docs/source/models.rst

@@ -5,7 +5,7 @@ ODM2 is organized with a "core" schema and multiple "extension" schemas that
 extend the functionality of the core. The following sections cover some overarching concepts
 for ODM2 and then focus on specific entities within the ODM2 Core schema and ODM2's extension schemas.
 
-ODM2Core Entities
+ODM2Core entities
 ------------------
 
 The following are entities in the `ODM2 Core Schema <http://odm2.github.io/ODM2/schemas/ODM2_Current/diagrams/ODM2Core.html>`__: