Add docstrings to patroni.__init__ (#2698)

References: PAT-111

patroni/__init__.py

@@ -1,3 +1,10 @@
+"""Define general variables and functions for :mod:`patroni`.
+
+:var PATRONI_ENV_PREFIX: prefix for Patroni related configuration environment variables.
+:var KUBERNETES_ENV_PREFIX: prefix for Kubernetes related configuration environment variables.
+:var MIN_PSYCOPG2: minimum version of :mod:`psycopg2` required by Patroni to work.
+"""
+
 import sys
 
 from typing import Any, Callable, Iterator, Tuple
@@ -8,12 +15,40 @@ MIN_PSYCOPG2 = (2, 5, 4)
 
 
 def fatal(string: str, *args: Any) -> None:
-    sys.stderr.write('FATAL: ' + string.format(*args) + '\n')
-    sys.exit(1)
+    """Write a fatal message to stderr and exit with code ``1``.
+
+    :param string: message to be written before exiting.
+    """
+    sys.exit('FATAL: ' + string.format(*args))
 
 
 def parse_version(version: str) -> Tuple[int, ...]:
+    """Convert *version* from human-readable format to tuple of integers.
+
+    .. note::
+        Designed for easy comparison of software versions in Python.
+
+    :param version: human-readable software version, e.g. ``2.5.4``.
+
+    :returns: tuple of *version* parts, each part as an integer.
+
+    :Example:
+
+        >>> parse_version('2.5.4')
+        (2, 5, 4)
+    """
     def _parse_version(version: str) -> Iterator[int]:
+        """Yield each part of a human-readable version string as an integer.
+
+        :param version: human-readable software version, e.g. ``2.5.4``.
+
+        :yields: each part of *version* as an integer.
+
+        :Example:
+
+            >>> tuple(_parse_version('2.5.4'))
+            (2, 5, 4)
+        """
         for e in version.split('.'):
             try:
                 yield int(e)
@@ -22,9 +57,22 @@ def parse_version(version: str) -> Tuple[int, ...]:
     return tuple(_parse_version(version.split(' ')[0]))
 
 
-# We pass MIN_PSYCOPG2 and parse_version as arguments to simplify usage of check_psycopg from the setup.py
 def check_psycopg(_min_psycopg2: Tuple[int, ...] = MIN_PSYCOPG2,
                   _parse_version: Callable[[str], Tuple[int, ...]] = parse_version) -> None:
+    """Ensure at least one among :mod:`psycopg2` or :mod:`psycopg` libraries are available in the environment.
+
+    .. note::
+        We pass ``MIN_PSYCOPG2`` and :func:`parse_version` as arguments to simplify usage of :func:`check_psycopg` from
+        the ``setup.py``.
+
+    .. note::
+        Patroni chooses :mod:`psycopg2` over :mod:`psycopg`, if possible.
+
+        If nothing meeting the requirements is found, then exit with a fatal message.
+
+    :param _min_psycopg2: minimum required version in case :mod:`psycopg2` is chosen.
+    :param _parse_version: function used to parse :mod:`psycopg2`/:mod:`psycopg` version into a comparable object.
+    """
     min_psycopg2_str = '.'.join(map(str, _min_psycopg2))
 
     # try psycopg2