Adding more glue content to docs

diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
index fd103a380884002915b40c66992c4924ac322c7a..16d1ba1294a2fe4483fad107279f4f579583f54c 100644 (file)
--- a/docs/advanced/index.rst
+++ b/docs/advanced/index.rst
@@ -1,5 +1,11 @@
-Advanced topics
-===============
+.. _advanced:
+
+More advanced topics
+====================
+
+Once you have familiarised yourself with the :ref:`Psycopg basic operations
+<basic>`, you can take a look at the chapter of this section for more advanced
+usages.
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/api/index.rst b/docs/api/index.rst
index 6ff1e157ac8f8525a8559aece8c7ce5a11180657..6ea9b60104ce143c7f9260bf816c0f147ae52be3 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -1,6 +1,12 @@
 Psycopg 3 API
 =============
 
+.. _api:
+
+This sections is a reference for all the public objects exposed by the
+`psycopg` module. For a more conceptual description you can take a look at
+:ref:`basic` and :ref:`advanced`.
+
 .. toctree::
     :maxdepth: 2
     :caption: Contents:

diff --git a/docs/basic/index.rst b/docs/basic/index.rst
index 73648d28db79a3ea5a482bacec382a460e2d6cab..b8f2e17ebacb89e861d07d8899ec3a071661b893 100644 (file)
--- a/docs/basic/index.rst
+++ b/docs/basic/index.rst
@@ -1,3 +1,4 @@
+.. _basic:
 
 Getting started with Psycopg 3
 ==============================

diff --git a/docs/basic/usage.rst b/docs/basic/usage.rst
index 8958cf1cd5886236152a8f266a311b875fe0be00..edbc7c925351425318818389da34b54f221bf1ce 100644 (file)
--- a/docs/basic/usage.rst
+++ b/docs/basic/usage.rst
@@ -98,6 +98,52 @@ relate to each other:
     - :ref:`transactions`.
 
 
+Shortcuts
+---------
+
+The pattern above is familiar to `!psycopg2` users. However, Psycopg 3 also
+exposes a few simple extensions which make the above pattern leaner:
+
+- the `Connection` objects exposes a `~Connection.execute()` method,
+  equivalent to creating a cursor, calling its `~Cursor.execute()` method, and
+  returning it.
+
+  .. code::
+
+      # This
+      cur = conn.execute(...)
+
+      # is equivalent to:
+      cur = conn.cursor()
+      cur.execute(...)
+
+- The `Cursor.execute()` method returns `!self`. This means that you can chain
+  a fetch operation, such as `~Cursor.fetchone()`, to the `!execute()` call:
+
+  .. code::
+
+      # This
+      cur.execute(...)
+      record = cur.fetchone()
+
+      cur.execute(...)
+      for record in cur:
+          ...
+
+      # is equivalent to:
+      record = cur.execute(...).fetchone()
+      for record in cur.execute(...):
+          ...
+
+Using them together, in simple cases, you can go from creating a connection to
+using a result in a single expression:
+
+.. code::
+
+    print(psycopg.connect(DSN).execute("select now()").fetchone()[0])
+    # 2042-07-12 18:15:10.706497+01:00
+
+
 .. index::
     pair: Connection; ``with``
 

diff --git a/docs/conf.py b/docs/conf.py
index b4bd5f29a0ff6a9b28bbb3e10e026a894b6b824b..00e9e94fbd34ceb0346ddfcc84a5d1833eb6c0c9 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,6 +17,8 @@
 import sys
 from pathlib import Path
 
+import psycopg
+
 docs_dir = Path(__file__).parent
 sys.path.append(str(docs_dir / "lib"))
 
@@ -26,7 +28,7 @@ sys.path.append(str(docs_dir / "lib"))
 project = "psycopg"
 copyright = "2020-2021, Daniele Varrazzo and The Psycopg Team"
 author = "Daniele Varrazzo"
-release = "UNRELEASED"
+release = psycopg.__version__
 
 
 # -- General configuration ---------------------------------------------------