Minor documentation improvements

Author: aboudreault

docs/getting_started.rst

@@ -40,14 +40,35 @@ behavior in some other way, this is the place to do it:
 
 .. code-block:: python
 
-    from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT
-    from cassandra.query import tuple_factory
+    from cassandra.cluster import Cluster
+    cluster = Cluster(['192.168.0.1', '192.168.0.2'], port=..., ssl_context=...)
 
-    profile = ExecutionProfile(row_factory=tuple_factory)
-    cluster = Cluster(execution_profiles={EXEC_PROFILE_DEFAULT: profile})
+Instantiating a :class:`~.Cluster` does not actually connect us to any nodes.
+To establish connections and begin executing queries we need a
+:class:`~.Session`, which is created by calling :meth:`.Cluster.connect()`:
+
+.. code-block:: python
+
+    cluster = Cluster()
     session = cluster.connect()
 
-    print(session.execute("SELECT release_version FROM system.local").one())
+The :meth:`~.Cluster.connect()` method takes an optional ``keyspace`` argument
+which sets the default keyspace for all queries made through that :class:`~.Session`:
+
+.. code-block:: python
+
+    cluster = Cluster()
+    session = cluster.connect('mykeyspace')
+
+
+You can always change a Session's keyspace using :meth:`~.Session.set_keyspace` or
+by executing a ``USE <keyspace>`` query:
+
+.. code-block:: python
+
+    session.set_keyspace('users')
+    # or you can do this instead
+    session.execute('USE users')
 
 Profiles are passed in by ``execution_profiles`` dict.
 
@@ -83,33 +104,6 @@ Users are free to setup additional profiles to be used by name:
 
 Also, parameters passed to ``Session.execute`` or attached to ``Statement``\s are still honored as before.
 
-Instantiating a :class:`~.Cluster` does not actually connect us to any nodes.
-To establish connections and begin executing queries we need a
-:class:`~.Session`, which is created by calling :meth:`.Cluster.connect()`:
-
-.. code-block:: python
-
-    cluster = Cluster()
-    session = cluster.connect()
-
-The :meth:`~.Cluster.connect()` method takes an optional ``keyspace`` argument
-which sets the default keyspace for all queries made through that :class:`~.Session`:
-
-.. code-block:: python
-
-    cluster = Cluster()
-    session = cluster.connect('mykeyspace')
-
-
-You can always change a Session's keyspace using :meth:`~.Session.set_keyspace` or
-by executing a ``USE <keyspace>`` query:
-
-.. code-block:: python
-
-    session.set_keyspace('users')
-    # or you can do this instead
-    session.execute('USE users')
-
 Executing Queries
 -----------------
 Now that we have a :class:`.Session` we can begin to execute queries. The simplest

docs/security.rst

@@ -99,7 +99,10 @@ SSL Configuration Examples
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 Here, we'll describe the server and driver configuration necessary to set up SSL to meet various goals, such as the client verifying the server and the server verifying the client. We'll also include Python code demonstrating how to use servers and drivers configured in these ways.
 
-**No identity verification**
+.. _ssl-no-identify-verification:
+
+No identity verification
+++++++++++++++++++++++++
 
 No identity verification at all. Note that this is not recommended for for production deployments.
 
@@ -123,7 +126,10 @@ The driver configuration:
     cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
     session = cluster.connect()
 
-**Client verifies server**
+.. _ssl-client-verifies-server:
+
+Client verifies server
+++++++++++++++++++++++
 
 Ensure the python driver verifies the identity of the server.
 
@@ -166,7 +172,10 @@ Additionally, you can also force the driver to verify the `hostname` of the serv
     cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context, ssl_options=ssl_options)
     session = cluster.connect()
 
-**Server verifies client**
+.. _ssl-server-verifies-client:
+
+Server verifies client
+++++++++++++++++++++++
 
 If Cassandra is configured to verify clients (``require_client_auth``), you need to generate
 SSL key and certificate files.
@@ -229,8 +238,10 @@ Finally, you can use that configuration with the following driver code:
     cluster = Cluster(['127.0.0.1'], ssl_context=ssl_context)
     session = cluster.connect()
 
+.. _ssl-server-client-verification:
 
-**Server verifies client and client verifies server**
+Server verifies client and client verifies server
++++++++++++++++++++++++++++++++++++++++++++++++++
 
 See the previous section for examples of Cassandra configuration and preparing
 the client certificates.