Docs: Update Salesforce (#399)

* add Authentication Guide, improve Overview and Quickstart, fix typos

* fix indentation

* clarify where to find the security token

docs/salesforce.rst

@@ -1,27 +1,50 @@
 Salesforce
 ==========
 
-`Salesforce <https://www.salesforce.com>`_ is a cloud-based CRM with a huge share of the for-profit
-and apolitical non-profit markets.
+`Salesforce <https://www.salesforce.com>`_ is a cloud-based CRM (customer relationship management) tool
+with a huge share of the for-profit and apolitical non-profit markets. This Parsons integration with the
+`Salesforce REST API <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_what_is_rest_api.htm>`_
+provides methods to describe objects and fields, handle records, and submit Salesforce
+`SOQL queries <https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm>`_
+that return a Parsons Table.
+
+The ``Salesforce`` class utilizes the `Simple Salesforce <https://simple-salesforce.readthedocs.io/en/latest/>`_
+client for making API calls under the hood.
+
+.. note::
+  Authentication
+    ``Salesforce`` requires your Salesforce username and password, as well as a security token
+    which can be acquired or reset by logging in to your Salesforce account and navigating to
+    *Settings > My Personal Information > Reset My Security Token*.
 
 ***********
 Quick Start
 ***********
 
+To instantiate the ``Salesforce`` class, you can store your Salesforce username, password,
+and security token as environmental variables (``SALESFORCE_USERNAME``, ``SALESFORCE_PASSWORD``,
+and ``SALESFORCE_SECURITY_TOKEN``, respectively) or pass them in as arguments:
+
 .. code-block:: python
-	
-	from parsons import Salesforce, Table
+    from parsons import Salesforce, Table
+
+    # First approach: Pass API credentials as environmental variables
+    sf = Salesforce()
 
-	sf = Salesforce()
+    # Second approach: Pass API credentials as arguments
+    sf = Salesforce(username='my@email', password='my_password', security_token='123')
 
-	# Get IDs and names for all Contacts
-	all_contacts = sf.query("SELECT Id, firstname, lastname FROM Contact")
+You can then call different endpoints:
+
+.. code-block:: python
+    # Get IDs and names for all Contacts
+    all_contacts = sf.query("SELECT Id, firstname, lastname FROM Contact")
 
-	# Get IDs, names, and email addresses from Contacts with a specific value for a custom field
-	ak_contacts = sf.query("SELECT Id, firstname, lastname, email FROM Contact WHERE digital_source__c == 'AK'")
+    # Get IDs, names, and email addresses from Contacts with a specific value for a custom field
+    ak_contacts = sf.query("SELECT Id, firstname, lastname, email FROM Contact WHERE digital_source__c == 'AK'")
 
-	# Update existing Contacts and create new records based on data in a Parsons Table
-	upsert_results = sf.upsert('Contact', contacts_table, 'id')
+    # Update existing Contacts and create new records based on data in a Parsons Table
+    upsert_results = sf.upsert('Contact', contacts_table, 'id')
 
 ***
 API

parsons/salesforce/salesforce.py

@@ -9,6 +9,8 @@
 
 class Salesforce:
     """
+    Instantiate the Salesforce class
+
     `Args:`
         username: str
             The Salesforce username (usually an email address). Not required if
@@ -21,7 +23,7 @@ class Salesforce:
             Settings > My Personal Information > Reset My Security Token.
             Not required if ``SALESFORCE_SECURITY_TOKEN`` env variable is passed.
         test_environment: bool
-            If ``True`` the client will connect to a Saleforce sandbox instance. Not required if
+            If ``True`` the client will connect to a Salesforce sandbox instance. Not required if
             ``SALESFORCE_DOMAIN`` env variable is passed.
     `Returns:`
         Salesforce class
@@ -69,7 +71,7 @@ def query(self, soql):
         `Args:`
             soql: str
                 The desired query in Salesforce SOQL language (SQL with additional limitations).
-                For reference, see `Salesforce SOQL documentation<https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm>`_.
+                For reference, see the `Salesforce SOQL documentation <https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm>`_.
         `Returns:`
             list of dicts with Salesforce data
         """ # noqa: E501,E261