chore: enable and clean up pydocstyle

Enabled pydocstyle checks to get some consistency on our documentation
strings.

python/understack-workflows/pyproject.toml

@@ -53,6 +53,7 @@ fix = true
 
 [tool.ruff.lint]
 select = [
+  "D",       # pydocstyle
   "E",       # pycodestyle (error)
   "F",       # pyflakes
   "B",       # flake8-bugbear
@@ -61,5 +62,18 @@ select = [
   "ASYNC",   # flake8-async
 ]
 
+ignore = [
+    "D100",  # don't require docs for every module
+    "D101",  # don't require docs for every class
+    "D102",  # don't require docs for every class method
+    "D103",  # don't require docs for every function
+    "D104",  # don't require docs for every package
+    "D417"   # don't require docs for every function parameter
+]
+
 [tool.ruff.lint.isort]
 force-single-line = true
+
+[tool.ruff.lint.pydocstyle]
+# enable the google doc style rules by default
+convention = "google"

python/understack-workflows/understack_workflows/ironic/client.py

@@ -12,6 +12,7 @@ def __init__(
         auth_url: str,
         tenant_name: str,
     ) -> None:
+        """Initialize our ironicclient wrapper."""
         self.svc_url = svc_url
         self.username = username
         self.password = password

python/understack-workflows/understack_workflows/ironic/secrets.py

@@ -6,7 +6,7 @@
 
 
 def read_secret(secret_name: str) -> str:
-    """Retrieve value of Kubernetes secret"""
+    """Retrieve value of Kubernetes secret."""
 
     def normalized(name):
         return re.sub(r"[^A-Za-z0-9-_]", "", name)

python/understack-workflows/understack_workflows/main/synchronize_interfaces.py

@@ -17,11 +17,11 @@
 
 
 def get_nautobot_interfaces(device_id: UUID) -> list[PortConfiguration]:
-    """
-    Return a List of Ironic Ports for all Nautobot Interfaceswith a
+    """Provides Nautobot to Ironic ports.
+
+    Return a List of Ironic Ports for all Nautobot Interfaces with a
     MAC address, for the specified Device.
     """
-
     nautobot_api = os.environ["NAUTOBOT_API"]
     nautobot_token = os.environ["NAUTOBOT_TOKEN"]
     nautobot = pynautobot.api(nautobot_api, nautobot_token)
@@ -39,7 +39,8 @@ def get_nautobot_interfaces(device_id: UUID) -> list[PortConfiguration]:
 
 
 def get_patch(nautobot_port: PortConfiguration, port: Port) -> list:
-    """
+    """Generate patch to change data.
+
     Compare attributes between Port objects and return a patch object
     containing any changes.
     """

python/understack-workflows/understack_workflows/main/synchronize_obm_creds.py

@@ -27,10 +27,7 @@ def event_to_node_configuration(event: dict) -> IronicNodeConfiguration:
 
 
 def credential_secrets():
-    """
-    Returns name of the Kubernetes Secret used to store OBM credentials
-    for server node_id
-    """
+    """Reads Kubernetes Secret files with username/password credentials."""
     username = None
     password = None
     with open("/etc/obm/username") as f:

python/understack-workflows/understack_workflows/nautobot.py

@@ -17,6 +17,7 @@ class Interface(Protocol):
 
 class Nautobot:
     def __init__(self, url, token, logger=None, session=None):
+        """Initialize our Nautobot API wrapper."""
         self.url = url
         self.token = token
         self.logger = logger or logging.getLogger(__name__)