Main interest point in docs landing page

diff --git a/docs/Makefile b/docs/Makefile
index 64011e35f73b32b2480246358ec7269bd3ed25c6..51572b5a9cd73aab93c73dbe353611ac8e0b8c77 100644 (file)
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -13,7 +13,10 @@ PYTHON        ?= python3
 help:
        @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) || true
 
-.PHONY: help env Makefile
+serve:
+       PSYCOPG3_IMPL=python sphinx-autobuild . _build/html/
+
+.PHONY: help serve env Makefile
 
 env: .venv
 

diff --git a/docs/async.rst b/docs/async.rst
index 12e3ff1fea3da45f88a6b86502631b98a73f591d..fbc851c7a8a7befb0349db68b05bd506b190a5bf 100644 (file)
--- a/docs/async.rst
+++ b/docs/async.rst
@@ -2,6 +2,8 @@
 
 .. index:: asyncio
 
+.. _async:
+
 Async operations
 ================
 

diff --git a/docs/index.rst b/docs/index.rst
index c1bad2e32ceecd701a644dc1f97994d0ee670cba..d411614af7d27079d9638834fe391e18194a47c5 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,17 +7,23 @@ programming language.
 
 `!psycopg3` presents a familiar interface for everyone who has used
 `!psycopg2` or any other `DB API 2.0`__ database adapter, but allows to use
-more modern PostgreSQL and Python features, such as `asyncio` support,
-server-side parameters binding, binary communication, a better integration of
-the COPY support.
+more modern PostgreSQL and Python features, such as:
+
+- :ref:`asynchronous support <async>`
+- :ref:`server-side parameters binding <server-side-binding>`
+- :ref:`binary communication <binary-data>`
+- :ref:`a great integration of the COPY support <copy>`
+- :ref:`direct access to the libpq functionalities <psycopg3.pq>`
 
 .. _Python: https://www.python.org/
 .. _PostgreSQL: https://www.postgresql.org/
 .. __: https://www.python.org/dev/peps/pep-0249/
 
+Documentation
+=============
+
 .. toctree::
     :maxdepth: 1
-    :caption: Contents:
 
     basic/index
     advanced/index

diff --git a/docs/params.rst b/docs/params.rst
index bf0b901c2bbe3841362ddb3dbf14feac8fb413e0..d459985e77df3653b874379dcef809770b6ceab3 100644 (file)
--- a/docs/params.rst
+++ b/docs/params.rst
@@ -197,4 +197,3 @@ Binary parameters and results
 
     - pass parameters in binary with ``%b``
     - return parameters in binary with `!cursor(format=BINARY)`
-

diff --git a/docs/pq.rst b/docs/pq.rst
index 9b500f4d29b174b09d76adc86724afc81076fd49..a0d3265d4a575073b04f70b84c8e306e27051bd8 100644 (file)
--- a/docs/pq.rst
+++ b/docs/pq.rst
@@ -1,3 +1,5 @@
+.. _psycopg3.pq:
+
 `pq` -- Libpq wrapper module
 ============================
 
@@ -73,10 +75,12 @@ Module content
 .. autofunction:: error_message
 
 
-Objects
--------
+Objects wrapping libpq structures and functions
+-----------------------------------------------
+
+.. admonition:: TODO
 
-TODO: finish documentation
+    finish documentation
 
 .. autoclass:: PGconn()
     :members:

diff --git a/psycopg3/psycopg3/pq/misc.py b/psycopg3/psycopg3/pq/misc.py
index f4a02bf59270b9d2dfb2a38eb100ef91184657f4..450a2d190a0cc56c9866960ab569ae5ae9f899bc 100644 (file)
--- a/psycopg3/psycopg3/pq/misc.py
+++ b/psycopg3/psycopg3/pq/misc.py
@@ -43,11 +43,12 @@ class PGresAttDesc(NamedTuple):
 
 def error_message(obj: Union[PGconn, PGresult], encoding: str = "utf8") -> str:
     """
-    Return an error message from a PGconn or PGresult.
+    Return an error message from a `PGconn` or `PGresult`.
 
-    The return value is a str (unlike pq data which is usually bytes): use
-    the connection encoding if available, otherwise the *encoding* parameter
-    as a fallback for decoding. Don't raise exception on decode errors.
+    The return value is a `!str` (unlike pq data which is usually `!bytes`):
+    use the connection encoding if available, otherwise the *encoding*
+    parameter as a fallback for decoding. Don't raise exceptions on decoding
+    errors.
 
     """
     bmsg: bytes