Merge pull request #1161 from VWS-Python/replace-docformatter-with-pydocstringformatter

Replace docformatter with pydocstringformatter

Author: adamtheturtle

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ ci:
     - check-manifest
     - deptry
     - doc8
-    - docformatter
+    - pydocstringformatter
     - docs
     - interrogate
     - interrogate-docs
@@ -103,9 +103,9 @@ repos:
         additional_dependencies: [uv==0.9.5]
         stages: [pre-commit]
 
-      - id: docformatter
-        name: docformatter
-        entry: uv run --extra=dev -m docformatter --in-place
+      - id: pydocstringformatter
+        name: pydocstringformatter
+        entry: uv run --extra=dev pydocstringformatter
         language: python
         types_or: [python]
         additional_dependencies: [uv==0.9.5]

docs/source/__init__.py

@@ -1,3 +1 @@
-"""
-Documentation.
-"""
+"""Documentation."""

docs/source/conf.py

@@ -1,7 +1,5 @@
 #!/usr/bin/env python3
-"""
-Configuration for Sphinx.
-"""
+"""Configuration for Sphinx."""
 
 # pylint: disable=invalid-name
 

pyproject.toml

@@ -43,12 +43,12 @@ optional-dependencies.dev = [
     "deptry==0.24.0",
     "doc8==2.0.0",
     "doccmd==2026.1.23.4",
-    "docformatter==1.7.7",
     "furo==2025.12.19",
     "interrogate==1.7.0",
     "mypy[faster-cache]==1.19.1",
     "mypy-strict-kwargs==2026.1.12",
     "prek==0.3.0",
+    "pydocstringformatter==0.7.3",
     "pylint[spelling]==4.0.4",
     "pyproject-fmt==2.11.1",
     "pyrefly==0.49.0",
@@ -116,15 +116,23 @@ lint.select = [
 lint.ignore = [
     # Ruff warns that this conflicts with the formatter.
     "COM812",
-    # Allow our chosen docstring line-style - no one-line summary.
-    "D200",
+    # Allow our chosen docstring line-style - pydocstringformatter handles formatting
+    # but doesn't enforce D205 (blank line after summary) or D212 (summary on first line).
     "D205",
     "D212",
     "D415",
     # Ruff warns that this conflicts with the formatter.
     "ISC001",
 ]
 
+lint.per-file-ignores."doccmd_*.py" = [
+    # Allow our chosen docstring line-style - pydocstringformatter handles
+    # formatting but docstrings in docs may not match this style.
+    "D200",
+    # Allow asserts in docs.
+    "S101",
+]
+
 lint.per-file-ignores."tests/*.py" = [
     # Allow 'assert' as we use it for tests.
     "S101",
@@ -245,9 +253,6 @@ spelling-private-dict-file = 'spelling_private_dict.txt'
 # --spelling-private-dict-file option instead of raising a message.
 spelling-store-unknown-words = 'no'
 
-[tool.docformatter]
-make-summary-multi-line = true
-
 [tool.check-manifest]
 
 ignore = [
@@ -318,6 +323,12 @@ enableTypeIgnoreComments = false
 reportUnnecessaryTypeIgnoreComment = true
 typeCheckingMode = "strict"
 
+[tool.pydocstringformatter]
+write = true
+split-summary-body = false
+max-line-length = 75
+linewrap-full-docstring = true
+
 [tool.interrogate]
 fail-under = 100
 omit-covered-files = true

src/vws_web_tools/__init__.py

@@ -1,6 +1,4 @@
-"""
-Tools for interacting with the VWS (Vuforia Web Services) website.
-"""
+"""Tools for interacting with the VWS (Vuforia Web Services) website."""
 
 import contextlib
 import time
@@ -21,9 +19,7 @@
 
 @beartype
 class DatabaseDict(TypedDict):
-    """
-    A dictionary type which represents a database.
-    """
+    """A dictionary type which represents a database."""
 
     database_name: str
     server_access_key: str
@@ -38,9 +34,7 @@ def log_in(
     email_address: str,
     password: str,
 ) -> None:  # pragma: no cover
-    """
-    Log in to Vuforia web services.
-    """
+    """Log in to Vuforia web services."""
     log_in_url = "https://developer.vuforia.com/vui/auth/login"
     driver.get(url=log_in_url)
     email_address_input_element = driver.find_element(
@@ -76,9 +70,7 @@ def create_license(
     driver: WebDriver,
     license_name: str,
 ) -> None:  # pragma: no cover
-    """
-    Create a license.
-    """
+    """Create a license."""
     licenses_url = "https://developer.vuforia.com/vui/develop/licenses"
     driver.get(url=licenses_url)
 
@@ -130,9 +122,7 @@ def create_database(
     database_name: str,
     license_name: str,
 ) -> None:  # pragma: no cover
-    """
-    Create a database.
-    """
+    """Create a database."""
     target_manager_url = "https://developer.vuforia.com/vui/develop/databases"
     driver.get(url=target_manager_url)
     ten_second_wait = WebDriverWait(driver=driver, timeout=10)
@@ -198,9 +188,7 @@ def get_database_details(
     driver: WebDriver,
     database_name: str,
 ) -> DatabaseDict:  # pragma: no cover
-    """
-    Get details of a database.
-    """
+    """Get details of a database."""
     target_manager_url = "https://developer.vuforia.com/vui/develop/databases"
     driver.get(url=target_manager_url)
     ten_second_wait = WebDriverWait(driver=driver, timeout=10)
@@ -276,9 +264,7 @@ def get_database_details(
 @click.group(name="vws-web")
 @beartype
 def vws_web_tools_group() -> None:
-    """
-    Commands for interacting with VWS.
-    """
+    """Commands for interacting with VWS."""
 
 
 @click.command()
@@ -291,9 +277,7 @@ def create_vws_license(
     email_address: str,
     password: str,
 ) -> None:  # pragma: no cover
-    """
-    Create a license.
-    """
+    """Create a license."""
     driver = webdriver.Safari()
     log_in(driver=driver, email_address=email_address, password=password)
     wait_for_logged_in(driver=driver)
@@ -313,9 +297,7 @@ def create_vws_database(
     email_address: str,
     password: str,
 ) -> None:  # pragma: no cover
-    """
-    Create a database.
-    """
+    """Create a database."""
     driver = webdriver.Safari()
     log_in(driver=driver, email_address=email_address, password=password)
     wait_for_logged_in(driver=driver)
@@ -340,9 +322,7 @@ def show_database_details(
     *,
     env_var_format: bool,
 ) -> None:  # pragma: no cover
-    """
-    Show the details of a database.
-    """
+    """Show the details of a database."""
     driver = webdriver.Safari()
     log_in(driver=driver, email_address=email_address, password=password)
     wait_for_logged_in(driver=driver)

tests/__init__.py

@@ -1,3 +1 @@
-"""
-Tests.
-"""
+"""Tests."""

tests/conftest.py

@@ -1,16 +1,12 @@
-"""
-Configuration, plugins and fixtures for `pytest`.
-"""
+"""Configuration, plugins and fixtures for `pytest`."""
 
 import pytest
 from beartype import beartype
 
 
 @beartype
 def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
-    """
-    Apply the beartype decorator to all collected test functions.
-    """
+    """Apply the beartype decorator to all collected test functions."""
     for item in items:
         assert isinstance(item, pytest.Function)
         item.obj = beartype(obj=item.obj)

tests/test_help.py

@@ -1,6 +1,4 @@
-"""
-Tests for the VWS CLI help.
-"""
+"""Tests for the VWS CLI help."""
 
 import pytest
 from click.testing import CliRunner