Further docs cleanup

Recent Sphinx versions seem overly aggressive in autodetecting python,
or I just didn't notice the errors, so be explicit in what language to
use with code examples.

doc/src/advanced.rst

@@ -295,7 +295,9 @@ something to read::
                 print "Got NOTIFY:", notify.pid, notify.channel, notify.payload
 
 Running the script and executing a command such as :sql:`NOTIFY test, 'hello'`
-in a separate :program:`psql` shell, the output may look similar to::
+in a separate :program:`psql` shell, the output may look similar to:
+
+.. code-block:: none
 
     Waiting for notifications on channel 'test'
     Timeout

doc/src/conf.py

@@ -101,6 +101,10 @@ default_role = 'obj'
 # output. They are ignored by default.
 #show_authors = False
 
+# Using 'python' instead of the default gives warnings if parsing an example
+# fails, instead of defaulting to none
+highlight_language = 'python'
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 

doc/src/extras.rst

@@ -403,7 +403,7 @@ The individual messages in the replication stream are represented by
 
             class LogicalStreamConsumer(object):
 
-                ...
+                # ...
 
                 def __call__(self, msg):
                     self.process_message(msg.payload)
@@ -501,7 +501,7 @@ The individual messages in the replication stream are represented by
       from datetime import datetime
 
       def consume(msg):
-          ...
+          # ...
 
       keepalive_interval = 10.0
       while True:

doc/src/faq.rst

@@ -306,7 +306,9 @@ I can't compile `!psycopg2`: the compiler says *error: libpq-fe.h: No such file
     API support (*i.e.* the libpq used at compile time was at least 9.3) but
     at runtime an older libpq dynamic library is found.
 
-    You can use::
+    You can use:
+
+    .. code-block:: shell
 
         $ ldd /path/to/packages/psycopg2/_psycopg.so | grep libpq
 

doc/src/usage.rst

@@ -48,7 +48,7 @@ The main entry points of Psycopg are:
 
 - The class `connection` encapsulates a database session. It allows to:
 
-  - create new `cursor`\s using the `~connection.cursor()` method to
+  - create new `cursor` instances using the `~connection.cursor()` method to
     execute database commands and queries,
 
   - terminate transactions using the methods `~connection.commit()` or
@@ -73,30 +73,40 @@ The main entry points of Psycopg are:
 Passing parameters to SQL queries
 ---------------------------------
 
-Psycopg casts Python variables to SQL literals by type.  Many standard Python types
+Psycopg converts Python variables to SQL values using their types: the Python
-are already `adapted to the correct SQL representation`__.
+type determines the function used to convert the object into a string
+representation suitable for PostgreSQL.  Many standard Python types are
+already `adapted to the correct SQL representation`__.
 
 .. __: python-types-adaptation_
 
-Example: the Python function call::
+Passing parameters to an SQL statement happens in functions such as
+`cursor.execute()` by using ``%s`` placeholders in the SQL statement, and
+passing a sequence of values as the second argument of the function. For
+example the Python function call::
 
-    >>> cur.execute(
+    >>> cur.execute("""
-    ...     """INSERT INTO some_table (an_int, a_date, a_string)
+    ...     INSERT INTO some_table (an_int, a_date, a_string)
-    ...         VALUES (%s, %s, %s);""",
+    ...     VALUES (%s, %s, %s);
+    ...     """,
     ...     (10, datetime.date(2005, 11, 18), "O'Reilly"))
 
-is converted into the SQL command::
+is converted into a SQL command similar to:
+
+.. code-block:: sql
 
     INSERT INTO some_table (an_int, a_date, a_string)
-     VALUES (10, '2005-11-18', 'O''Reilly');
+    VALUES (10, '2005-11-18', 'O''Reilly');
 
-Named arguments are supported too using :samp:`%({name})s` placeholders.
+Named arguments are supported too using :samp:`%({name})s` placeholders in the
-Using named arguments the values can be passed to the query in any order and
+query and specifying the values into a mapping.  Using named arguments allows
-several placeholders can use the same value::
+to specify the values in any order and to repeat the same value in several
+places in the query::
 
-    >>> cur.execute(
+    >>> cur.execute("""
-    ...     """INSERT INTO some_table (an_int, a_date, another_date, a_string)
+    ...     INSERT INTO some_table (an_int, a_date, another_date, a_string)
-    ...         VALUES (%(int)s, %(date)s, %(date)s, %(str)s);""",
+    ...     VALUES (%(int)s, %(date)s, %(date)s, %(str)s);
+    ...     """,
     ...     {'int': 10, 'str': "O'Reilly", 'date': datetime.date(2005, 11, 18)})
 
 Using characters ``%``, ``(``, ``)`` in the argument names is not supported.
@@ -809,7 +819,9 @@ lifetime extends well after `~connection.commit()`, calling
     It is also possible to use a named cursor to consume a cursor created
     in some other way than using the |DECLARE| executed by
     `~cursor.execute()`. For example, you may have a PL/pgSQL function
-    returning a cursor::
+    returning a cursor:
+
+    .. code-block:: postgres
 
         CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS $$
         BEGIN