Tests: Refactor doctests/{connection,cursor,https}.txt into docs

src/crate/client/doctests/connection.txt → docs/by-example/connection.rst

@@ -1,7 +1,18 @@
-==========
-Connection
-==========
+=====================
+The Connection object
+=====================
 
+This documentation section outlines different attributes, methods, and
+behaviors of the ``crate.client.connection.Connection`` object.
+
+.. rubric:: Table of Contents
+
+.. contents::
+   :local:
+
+
+connect()
+=========
 ::
 
     >>> from crate.client import connect
@@ -12,6 +23,9 @@ We create a new connection object::
     >>> connection.lowest_server_version.version
     (2, 0, 0)
 
+cursor()
+========
+
 Calling the ``cursor()`` function on the connection will
 return a cursor object::
 
@@ -23,6 +37,9 @@ cursor object::
     >>> cursor.rowcount
     -1
 
+close()
+=======
+
 Now we close the connection::
 
     >>> connection.close()
@@ -45,9 +62,3 @@ raise a ``ProgrammingError``::
     Traceback (most recent call last):
     ...
     crate.client.exceptions.ProgrammingError: Connection closed
-
-    >>> connection = connect(client=connection_client_mocked)
-    >>> cursor = connection.cursor()
-    >>> cursor.rowcount
-    -1
-

src/crate/client/doctests/cursor.txt → docs/by-example/cursor.rst

@@ -1,6 +1,17 @@
-======
-Cursor
-======
+=================
+The Cursor object
+=================
+
+This documentation section outlines different attributes, methods, and
+behaviors of the ``crate.client.cursor.Cursor`` object.
+
+To improve focus and reduce boilerplate, it uses a ``set_next_response`` method
+only intended for testing.
+
+.. rubric:: Table of Contents
+
+.. contents::
+   :local:
 
 
 Setup
@@ -17,7 +28,8 @@ up the response for subsequent cursor operations.
     >>> connection = connect(client=connection_client_mocked)
     >>> cursor = connection.cursor()
 
-The rowcount and duration attribute is -1 in case no ``execute()`` has been performed on the cursor.
+The rowcount and duration attribute is ``-1``, in case no ``execute()`` has
+been performed on the cursor.
 
 ::
 
@@ -237,8 +249,8 @@ The attribute is -1 in case the cursor has been closed::
     ...     "cols":[ "name", "position" ],
     ... })
 
-executemany
-===========
+executemany()
+=============
 
 ``executemany()`` allows to execute a single sql statement against a sequence
 of parameters::

src/crate/client/doctests/https.txt → docs/by-example/https.rst

@@ -4,6 +4,18 @@
 HTTPS connection support
 ========================
 
+This documentation section outlines different options to connect to CrateDB
+using SSL/TLS.
+
+.. rubric:: Table of Contents
+
+.. contents::
+   :local:
+
+
+Introduction
+============
+
 The CrateDB client is able to connect via HTTPS.
 
 A check against a specific CA certificate can be made by creating the client
@@ -16,21 +28,17 @@ with the path to the CA certificate file using the keyword argument
     use the keyword argument ``verify_ssl_cert``. If it is set to ``False``,
     server certificate validation will be skipped.
 
+All the following examples will connect to a host using a self-signed
+certificate.
 
-.. rubric:: Table of Contents
-
-.. contents::
-   :local:
-
-Examples
-========
+The CrateDB Python driver package offers a HTTP client API object.
 
-All of the following examples will connect to a host using a self-signed
-certificate.
+    >>> from crate.client import http
+    >>> HttpClient = http.Client
 
 
 With certificate verification
------------------------------
+=============================
 
 When using a valid CA certificate, the connection will be successful::
 
@@ -56,7 +64,7 @@ Also, when providing an invalid ``ca_cert``, an error is raised::
 
 
 Without certificate verification
---------------------------------
+================================
 
 When turning off certificate verification, calling the server will succeed,
 even when not providing a valid CA certificate::
@@ -74,8 +82,8 @@ Without verification, calling the server will even work when using an invalid
 
 
 
-Client certificate
-------------------
+X.509 client certificate
+========================
 
 The CrateDB driver also supports client certificates.
 

docs/by-example/index.rst

@@ -10,14 +10,12 @@ About
 This part of the documentation contains examples how to use the CrateDB Python
 client, exercising different options and scenarios.
 
-
-*******
-Details
-*******
-
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     client
     http
+    https
     blob
+    connection
+    cursor

src/crate/client/tests.py

@@ -331,14 +331,6 @@ def test_suite():
     suite = unittest.TestSuite()
     flags = (doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS)
 
-    s = doctest.DocFileSuite(
-        'doctests/cursor.txt',
-        'doctests/connection.txt',
-        setUp=setUpMocked,
-        optionflags=flags,
-        encoding='utf-8'
-    )
-    suite.addTest(s)
     suite.addTest(unittest.makeSuite(CursorTest))
     suite.addTest(unittest.makeSuite(HttpClientTest))
     suite.addTest(unittest.makeSuite(KeepAliveClientTest))
@@ -353,15 +345,6 @@ def test_suite():
     suite.addTest(doctest.DocTestSuite('crate.client.connection'))
     suite.addTest(doctest.DocTestSuite('crate.client.http'))
 
-    s = doctest.DocFileSuite(
-        'doctests/https.txt',
-        setUp=setUpWithHttps,
-        optionflags=flags,
-        encoding='utf-8'
-    )
-    s.layer = HttpsTestServerLayer()
-    suite.addTest(s)
-
     s = doctest.DocFileSuite(
         'sqlalchemy/doctests/itests.txt',
         'sqlalchemy/doctests/dialect.txt',
@@ -397,4 +380,24 @@ def test_suite():
     s.layer = ensure_cratedb_layer()
     suite.addTest(s)
 
+    s = doctest.DocFileSuite(
+        'docs/by-example/connection.rst',
+        'docs/by-example/cursor.rst',
+        module_relative=False,
+        setUp=setUpMocked,
+        optionflags=flags,
+        encoding='utf-8'
+    )
+    suite.addTest(s)
+
+    s = doctest.DocFileSuite(
+        'docs/by-example/https.rst',
+        module_relative=False,
+        setUp=setUpWithHttps,
+        optionflags=flags,
+        encoding='utf-8'
+    )
+    s.layer = HttpsTestServerLayer()
+    suite.addTest(s)
+
     return suite