From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 26 Nov 2020 19:49:33 +0000 (+0000)
Subject: Main interest point in docs landing page
X-Git-Tag: 3.0.dev0~300
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=eefb388a7db222f97b666ac826c677a7fc446ece;p=thirdparty%2Fpsycopg.git

Main interest point in docs landing page
---

diff --git a/docs/Makefile b/docs/Makefile
index 64011e35f..51572b5a9 100644
--- 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 12e3ff1fe..fbc851c7a 100644
--- 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 c1bad2e32..d411614af 100644
--- 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 bf0b901c2..d459985e7 100644
--- 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 9b500f4d2..a0d3265d4 100644
--- 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 f4a02bf59..450a2d190 100644
--- 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