STY: Apply docformatter (#1584)

See https://pypi.org/project/docformatter/

I tried pre-commit, but docformatter collides with black for docstrings of functions that contain a function.

.pre-commit-config.yaml

@@ -10,10 +10,11 @@ repos:
     -   id: check-yaml
     -   id: debug-statements
     -   id: end-of-file-fixer
-        exclude: "resources/.*"
+        exclude: "resources/.*|docs/make.bat"
     -   id: trailing-whitespace
     -   id: mixed-line-ending
         args: ['--fix=lf']
+        exclude: "docs/make.bat"
     -   id: check-added-large-files
         args: ['--maxkb=1000']
 -   repo: https://github.com/pycqa/flake8
@@ -26,7 +27,7 @@ repos:
 #     hooks:
 #     -   id: mypy
 -   repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
     -   id: isort
         name: isort (python)
@@ -37,10 +38,11 @@ repos:
     -   id: black
         args: [--target-version, py36]
 -   repo: https://github.com/asottile/blacken-docs
-    rev: v1.12.1
+    rev: 1.13.0
     hooks:
     -   id: blacken-docs
         additional_dependencies: [black==22.1.0]
+        exclude: "docs/user/robustness.md"
 -   repo: https://github.com/asottile/pyupgrade
     rev: v3.3.1
     hooks:

docs/conf.py

@@ -1,8 +1,8 @@
 """
 Configuration file for the Sphinx documentation builder.
 
-This file only contains a selection of the most common options. For a full
-list see the documentation:
+This file only contains a selection of the most common options.
+For a full list see the documentation:
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 # -- Path setup --------------------------------------------------------------

docs/user/adding-pdf-annotations.md

@@ -136,6 +136,7 @@ writer.add_page(page)
 # Add the rectangle
 annotation = AnnotationBuilder.ellipse(
     rect=(50, 550, 200, 650),
+)
 writer.add_annotation(page_number=0, annotation=annotation)
 
 # Write the annotated file to disk

pypdf/_encryption.py

@@ -750,7 +750,7 @@ def generate_values(
     def compute_U_value(password: bytes, key: bytes) -> Tuple[bytes, bytes]:
         """
         Algorithm 3.8 Computing the encryption dictionary’s U (user password)
-        and UE (user encryption key) values
+        and UE (user encryption key) values.
 
         1. Generate 16 random bytes of data using a strong random number generator.
            The first 8 bytes are the User Validation Salt. The second 8 bytes
@@ -829,7 +829,8 @@ def compute_O_value(
     @staticmethod
     def compute_Perms_value(key: bytes, p: int, metadata_encrypted: bool) -> bytes:
         """
-        Algorithm 3.10 Computing the encryption dictionary’s Perms (permissions) value
+        Algorithm 3.10 Computing the encryption dictionary’s Perms
+        (permissions) value.
 
         1. Extend the permissions (contents of the P integer) to 64 bits by
            setting the upper 32 bits to all 1’s.

pypdf/_merger.py

@@ -374,18 +374,18 @@ def add_metadata(self, infos: Dict[str, Any]) -> None:
 
     def addMetadata(self, infos: Dict[str, Any]) -> None:  # deprecated
         """
-        .. deprecated:: 1.28.0
+        Use :meth:`add_metadata` instead.
 
-            Use :meth:`add_metadata` instead.
+        .. deprecated:: 1.28.0
         """
         deprecation_with_replacement("addMetadata", "add_metadata")
         self.add_metadata(infos)
 
     def setPageLayout(self, layout: LayoutType) -> None:  # deprecated
         """
-        .. deprecated:: 1.28.0
+        Use :meth:`set_page_layout` instead.
 
-            Use :meth:`set_page_layout` instead.
+        .. deprecated:: 1.28.0
         """
         deprecation_with_replacement("setPageLayout", "set_page_layout")
         self.set_page_layout(layout)
@@ -421,9 +421,9 @@ def set_page_layout(self, layout: LayoutType) -> None:
 
     def setPageMode(self, mode: PagemodeType) -> None:  # deprecated
         """
-        .. deprecated:: 1.28.0
+        Use :meth:`set_page_mode` instead.
 
-            Use :meth:`set_page_mode` instead.
+        .. deprecated:: 1.28.0
         """
         deprecation_with_replacement("setPageMode", "set_page_mode", "3.0.0")
         self.set_page_mode(mode)