From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 12 Jul 2021 17:32:14 +0000 (+0200)
Subject: Adding more glue content to docs
X-Git-Tag: 3.0.dev1~24
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f0805413be83e45c075049ac1d4185d951373290;p=thirdparty%2Fpsycopg.git

Adding more glue content to docs
---

diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
index fd103a380..16d1ba129 100644
--- 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 6ff1e157a..6ea9b6010 100644
--- 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 73648d28d..b8f2e17eb 100644
--- 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 8958cf1cd..edbc7c925 100644
--- 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 b4bd5f29a..00e9e94fb 100644
--- 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 ---------------------------------------------------