Documentation: Add some documentation edits to the "by-example" section

docs/by-example/sqlalchemy/getting-started.rst

@@ -169,8 +169,6 @@ levels of a ``Object`` type field. For example the following query will only
 update the ``gender`` key. The ``species`` key which is on the same level will
 be left untouched.
 
-::
-
     >>> char = session.query(Character).filter_by(name='Arthur Dent').one()
     >>> char.details['gender'] = 'manly man'
     >>> session.commit()
@@ -189,22 +187,24 @@ In addition to the ``Object`` type the CrateDB sqlalchemy dialect also includes
 a type called ``ObjectArray``. This type maps to a Python list of dictionaries.
 
 Note that opposed to the ``Object`` type the ``ObjectArray`` type isn't smart
-and doesn't have an intelligent change tracking. Therefore the generated UPDATE
-statement will affect the whole list:
+and doesn't have an intelligent change tracking. Therefore the generated
+``UPDATE`` statement will affect the whole list:
 
     >>> char.more_details = [{'foo': 1, 'bar': 10}, {'foo': 2}]
     >>> session.commit()
 
     >>> char.more_details.append({'foo': 3})
     >>> session.commit()
 
-This will generate an UPDATE statement roughly like this:
+This will generate an ``UPDATE`` statement which looks roughly like this::
+
+    "UPDATE characters SET more_details = ? ...", ([{'foo': 1, 'bar': 10}, {'foo': 2}, {'foo': 3}],)
 
-    "UPDATE characters set more_details = ? ...", ([{'foo': 1, 'bar': 10}, {'foo': 2}, {'foo': 3}],)
+.. hidden:
 
     >>> _ = connection.execute(text("REFRESH TABLE characters"))
 
-To do queries against fields of ``ObjectArray``s you have to use the
+To do queries against fields of ``ObjectArray`` types, you have to use the
 ``.any(value, operator=operators.eq)`` method on a subscript, because accessing
 fields of object arrays (e.g. ``Character.more_details['foo']``) returns an
 array of the field type.
@@ -306,8 +306,6 @@ CrateDB SQLAlchemy driver comes with a ``match`` function in the
 ``predicates`` namespace, which can be used to search on one or multiple
 fields.
 
-::
-
     >>> from crate.client.sqlalchemy.predicates import match
     >>> session.query(Character.name) \
     ...     .filter(match(Character.name_ft, 'Arthur')) \
@@ -417,10 +415,10 @@ Insert From Select
 
 In SQLAlchemy, the ``insert().from_select()`` function returns a new ``Insert``
 construct which represents an ``INSERT...FROM SELECT`` statement. This
-functionality is now supported by the ``crate`` client library. Here is an
-example that uses ``insert().from_select()``:
+functionality is supported by the CrateDB client library. Here is an example
+that uses ``insert().from_select()``.
 
-First let's define and create the tables:
+First, let's define and create the tables:
 
     >>> from sqlalchemy import select, insert
 
@@ -457,14 +455,16 @@ table:
     >>> ins = insert(ArchivedTasks).from_select(['id','content'], sel)
     >>> result = session.execute(ins)
     >>> session.commit()
-    >>> _ = connection.execute(text("REFRESH TABLE archived_tasks"))
 
-This will result in the following query:
+This will emit the following ``INSERT`` statement to the database::
+
+    INSERT INTO archived_tasks (id, content)
+        (SELECT todos.id, todos.content FROM todos WHERE todos.status = 'done')
 
-    "INSERT INTO archived_tasks (id, content) "
-    ... "(SELECT todos.id, todos.content FROM todos WHERE todos.status = 'done')"
+Now, verify that the data is present in the database:
 
-    >>> pprint([str(r) for r in session.execute("Select content from archived_tasks")])
+    >>> _ = connection.execute(text("REFRESH TABLE archived_tasks"))
+    >>> pprint([str(r) for r in session.execute("SELECT content FROM archived_tasks")])
     ["('Write Tests',)"]
 
 .. hidden: Disconnect from database

docs/by-example/sqlalchemy/inspection-reflection.rst

@@ -18,16 +18,18 @@ within SQLAlchemy Core and the SQLAlchemy ORM.
 The ``CrateDialect`` instance provides metadata about the CrateDB cluster,
 like version and schema information.
 
+As always, let's start with creating an ``Engine`` instance.
+
     >>> import sqlalchemy as sa
     >>> engine = sa.create_engine(f"crate://{crate_host}")
 
 
 Inspector
 =========
 
-The `SQLAlchemy inspector`_ is a low level interface which provides a backend-
-agnostic system of loading lists of schema, table, column, and constraint
-descriptions from a given database is available.
+The `SQLAlchemy inspector`_ is a low level interface which provides a
+backend-agnostic system of loading lists of schema, table, column, and
+constraint descriptions from a given database.
 
     >>> inspector = sa.inspect(engine)