Improve: convert docstrings to google convention (#298)

Author: Guts

.pre-commit-config.yaml

@@ -65,10 +65,13 @@ repos:
     rev: 7.0.0
     hooks:
       - id: flake8
+        additional_dependencies:
+          - flake8-docstrings<2
         language: python
         args:
           - --config=setup.cfg
           - --select=E9,F63,F7,F82
+          - --docstring-convention=google
 
 ci:
   autofix_prs: true

mkdocs_rss_plugin/config.py

@@ -18,8 +18,10 @@
 
 
 class _DateFromMeta(Config):
+    """Sub configuration object for related date options."""
+
     #  TODO: remove deprecated code in future version. Only str values will be accepted
-    # for  as_creation and as_update
+    # for as_creation and as_update
     as_creation = config_options.Type(Union[bool, str], default="git")
     as_update = config_options.Type(Union[bool, str], default="git")
     datetime_format = config_options.Type(str, default="%Y-%m-%d %H:%M")
@@ -28,6 +30,8 @@ class _DateFromMeta(Config):
 
 
 class _FeedsFilenamesConfig(Config):
+    """Sub configuration for feeds filenames."""
+
     json_created = config_options.Type(str, default="feed_json_created.json")
     json_updated = config_options.Type(str, default="feed_json_updated.json")
     rss_created = config_options.Type(str, default="feed_rss_created.xml")

mkdocs_rss_plugin/git_manager/ci.py

@@ -24,13 +24,14 @@
 # ############################################################################
 # ########## Functions #############
 # ##################################
+
+
 class CiHandler:
     def __init__(self, repo: Git):
         self.repo = repo
 
-    def raise_ci_warnings(self):
+    def raise_ci_warnings(self) -> None:
         """Raise warnings when users use mkdocs-rss-plugin on CI build runners."""
-
         if not self.is_shallow_clone():
             return None
 
@@ -86,11 +87,11 @@ def raise_ci_warnings(self):
                     """
             )
 
-    def commit_count(self) -> bool:
+    def commit_count(self) -> int:
         """Helper function to determine the number of commits in a repository.
 
-        :return: Number of commits
-        :rtype: bool
+        Returns:
+            int: Number of commits
         """
         refs = self.repo.for_each_ref().split("\n")
         refs = [x.split()[0] for x in refs]
@@ -101,12 +102,14 @@ def commit_count(self) -> bool:
         return max(counts)
 
     def is_shallow_clone(self) -> bool:
-        """Helper function to determine if repository is a shallow clone. \
+        """Helper function to determine if repository is a shallow clone.
+
         References & Context:
         - https://github.com/timvink/mkdocs-rss-plugin/issues/10
         - https://stackoverflow.com/a/37203240/5525118
 
-        :return: True if a repo is shallow clone
-        :rtype: bool
+
+        Returns:
+            bool: True if a repo is shallow clone
         """
         return path.exists(".git/shallow")

mkdocs_rss_plugin/plugin.py

@@ -58,7 +58,7 @@ class GitRssPlugin(BasePlugin[RssPluginConfig]):
     def __init__(self):
         """Instantiation."""
         # pages storage
-        self.pages_to_filter: list = []
+        self.pages_to_filter: list[PageInformation] = []
         # prepare output feeds
         self.feed_created: dict = {}
         self.feed_updated: dict = {}
@@ -308,17 +308,16 @@ def on_page_content(
             )
         )
 
-    def on_post_build(self, config: config_options.Config) -> dict | None:
-        """The post_build event does not alter any variables. \
-        Use this event to call post-build scripts. \
-        See: <https://www.mkdocs.org/user-guide/plugins/#on_post_build>
+    def on_post_build(self, config: config_options.Config) -> None:
+        """The post_build event does not alter any variables. Use this event to call
+            post-build scripts.
 
-        :param config: global configuration object
-        :type config: config_options.Config
-        :return: global configuration object
-        :rtype: dict
-        """
+        See:
+            <https://www.mkdocs.org/user-guide/plugins/#on_post_build>
 
+        Args:
+            config (config_options.Config): global configuration object
+        """
         # Skip if disabled
         if not self.config.enabled:
             return