DOC: Use google style docstrings (py-pdf#1534)

The Google Docstring style is way more readable than ReST style docstrings. For this reason, this PR replaces ReST style docstrings by Google Style docstrings.

Tools used:
- pyment
- pydocstyle

Other changes:
* DEV: Set python_use_unqualified_type_names=True
* MAINT: Additionally, most instances of 'pragma: no-cover' were replaced by the more descriptive 'deprecated'.
* DOC: Document how to document

docs/conf.py

@@ -1,9 +1,10 @@
-# 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:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+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:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -73,6 +74,8 @@
     "undoc-members": True,
 }
 autodoc_inherit_docstrings = False
+autodoc_typehints_format = "short"
+python_use_unqualified_type_names = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/dev/documentation.md

@@ -0,0 +1,56 @@
+# Documentation
+
+## API Reference
+
+### Method / Function Docstrings
+
+We use Google-Style Docstrings:
+
+```
+def example(param1: int, param2: str) -> bool:
+    """
+    Example function with PEP 484 type annotations.
+
+    Args:
+      param1: The first parameter.
+      param2: The second parameter.
+
+    Returns:
+      The return value. True for success, False otherwise.
+
+    Raises:
+      AttributeError: The ``Raises`` section is a list of all exceptions
+        that are relevant to the interface.
+      ValueError: If `param2` is equal to `param1`.
+
+    Examples:
+        Examples should be written in doctest format, and should illustrate how
+        to use the function.
+
+        >>> print([i for i in example_generator(4)])
+        [0, 1, 2, 3]
+    """
+```
+
+* The order of sections is (1) Args (2) Returns (3) Raises (4) Examples
+* If there is no return value, remove the
+* Properties should not have any sections
+
+
+## Issues and PRs
+
+An issue can be used to discuss what we want to achieve.
+
+A PR can be used to discuss how we achieve it.
+
+## Commit Messages
+
+We want to have descriptive commits in the `main` branch. For this reason, every
+pull request (PR) is squashed. That means no matter how many commits a PR has,
+in the end only one combined commit will be in `main`.
+
+The title of the PR will be used as the first line of that combined commit message.
+
+The first comment within the commit will be used as the message body.
+
+See [dev intro](intro.html#commit-messages)  for more details.

docs/index.rst

@@ -64,6 +64,7 @@ You can contribute to `pypdf on GitHub <https://github.com/py-pdf/pypdf>`_.
    dev/pdf-format
    dev/cmaps
    dev/deprecations
+   dev/documentation
    dev/testing
 
 .. toctree::

make_changelog.py

@@ -38,23 +38,27 @@ def main(changelog_path: str):
 
 
 def version_bump(git_tag: str) -> str:
+    """Increase the patch version of the git tag by one."""
     # just assume a patch version change
     major, minor, patch = git_tag.split(".")
     return f"{major}.{minor}.{int(patch) + 1}"
 
 
 def get_changelog(changelog_path: str) -> str:
+    """Read the changelog."""
     with open(changelog_path) as fh:
         changelog = fh.read()
     return changelog
 
 
 def write_changelog(new_changelog: str, changelog_path: str) -> None:
+    """Write the changelog."""
     with open(changelog_path, "w") as fh:
         fh.write(new_changelog)
 
 
 def get_formatted_changes(git_tag: str) -> str:
+    """Format the changes done since the last tag."""
     commits = get_git_commits_since_tag(git_tag)
 
     # Group by prefix
@@ -100,6 +104,7 @@ def get_formatted_changes(git_tag: str) -> str:
 
 
 def get_most_recent_git_tag():
+    """Get the git tag most recently created."""
     git_tag = str(
         subprocess.check_output(
             ["git", "describe", "--abbrev=0"], stderr=subprocess.STDOUT
@@ -109,6 +114,7 @@ def get_most_recent_git_tag():
 
 
 def get_git_commits_since_tag(git_tag) -> List[Change]:
+    """Get all commits since the last tag."""
     commits = str(
         subprocess.check_output(
             [
@@ -125,6 +131,7 @@ def get_git_commits_since_tag(git_tag) -> List[Change]:
 
 
 def parse_commit_line(line) -> Change:
+    """Parse the first line of a git commit message."""
     if "\\t" not in line:
         raise ValueError(f"Invalid commit line: {line}")
     commit_hash, rest = line.split("\\t", 1)

mutmut_config.py

@@ -6,6 +6,7 @@
 
 
 def pre_mutation(context):
+    """Filter what to mutate."""
     line = context.current_source_line.strip()
     if (
         "_codecs" in context.filename