Lex Napoleon

.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`.

docs/conf.py

@@ -18,6 +18,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "myst_parser",
     "notfound.extension",
 ]

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: