From 66b984797d7ce503acedb73bd932b162ba46aa9e Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Sat, 13 Jan 2024 13:50:58 +0100
Subject: [PATCH] Lex Napoleon

---
 .github/CONTRIBUTING.md        | 17 +++++++++++++----
 docs/conf.py                   |  1 +
 src/service_identity/hazmat.py | 10 ++++++----
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 9c37758..af5d8d1 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -109,16 +109,25 @@ But it's way more comfortable to run it locally and catch avoidable errors befor
 ## Code
 
 - Obey [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 257](https://www.python.org/dev/peps/pep-0257/).
-  We use the `"""`-on-separate-lines style for docstrings:
+  We use the `"""`-on-separate-lines style for docstrings with [Napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)-style API documentation:
 
   ```python
-  def func(x: str) -> str:
+  def func(x: str, y: int) -> str:
       """
       Do something.
 
-      :param str x: A very important parameter.
+      Args:
+          x: A very important parameter.
 
-      :rtype: str
+          y:
+              Another important parameter but one that doesn't fit a line so
+              it already starts on the next one.
+
+      Raises:
+          Exception: When Something goes wrong.
+
+      Returns:
+          A very important return value.
       """
   ```
 - If you add or change public APIs, tag the docstring using `..  versionadded:: 16.0.0 WHAT` or `..  versionchanged:: 16.2.0 WHAT`.
diff --git a/docs/conf.py b/docs/conf.py
index d072d82..66ebecc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,6 +18,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "myst_parser",
     "notfound.extension",
 ]
diff --git a/src/service_identity/hazmat.py b/src/service_identity/hazmat.py
index 6b9bf7b..19611d8 100644
--- a/src/service_identity/hazmat.py
+++ b/src/service_identity/hazmat.py
@@ -83,8 +83,8 @@ def _find_matches(
     """
     Search for matching certificate patterns and service_ids.
 
-    :param service_ids: List of service IDs like DNS_ID.
-    :type service_ids: `list`
+    Args:
+        service_ids: List of service IDs like DNS_ID.
     """
     matches = []
     for sid in service_ids:
@@ -102,9 +102,11 @@ def _is_ip_address(pattern: str | bytes) -> bool:
     """
     Check whether *pattern* could be/match an IP address.
 
-    :param pattern: A pattern for a host name.
+    Args:
+        pattern: A pattern for a host name.
 
-    :return: `True` if *pattern* could be an IP address, else `False`.
+    Returns:
+        `True` if *pattern* could be an IP address, else `False`.
     """
     if isinstance(pattern, bytes):
         try: