Docs: fix mkdocstings config and improve api autodoc (#357)

Author: Guts

docs/api.md

@@ -12,18 +12,32 @@ icon: fontawesome/solid/code
 
 ::: mkdocs_rss_plugin.config.RssPluginConfig
 
+::: mkdocs_rss_plugin.config._DateFromMeta
+
+::: mkdocs_rss_plugin.config._FeedsFilenamesConfig
+
 ----
 
 ::: mkdocs_rss_plugin.constants
 
-----
+## Models
 
 ::: mkdocs_rss_plugin.models.PageInformation
 
-----
-
-::: mkdocs_rss_plugin.util.Util
+::: mkdocs_rss_plugin.models.RssFeedBase
 
 ## Integrations
 
+::: mkdocs_rss_plugin.integrations.theme_material_base.IntegrationMaterialThemeBase
+
+::: mkdocs_rss_plugin.integrations.theme_material_blog_plugin.IntegrationMaterialBlog
+
 ::: mkdocs_rss_plugin.integrations.theme_material_social_plugin.IntegrationMaterialSocialCards
+
+## Utils
+
+::: mkdocs_rss_plugin.git_manager.ci.CiHandler
+
+::: mkdocs_rss_plugin.timezoner
+
+::: mkdocs_rss_plugin.util.Util

mkdocs.yml

@@ -91,13 +91,17 @@ plugins:
       handlers:
         python:
           options:
+            docstring_options:
+              ignore_init_summary: false
+              trim_doctest_flags: true
             docstring_style: google
+            find_stubs_package: true
             heading_level: 3
-            ignore_init_summary: false
+            show_bases: true
+            show_inheritance_diagram: true
+            show_root_heading: true
             show_source: false
-          merge_init_into_class: true
-          paths: [.]
-          show_root_heading: true
+            merge_init_into_class: true
 
   - privacy:
       enabled: !ENV [MKDOCS_ENABLE_PLUGIN_PRIVACY, true]

mkdocs_rss_plugin/constants.py

@@ -14,11 +14,11 @@
 # ########## Globals #############
 # ################################
 
-DEFAULT_CACHE_FOLDER = Path(".cache/plugins/rss")
-DEFAULT_TEMPLATE_FOLDER = Path(__file__).parent / "templates"
-DEFAULT_TEMPLATE_FILENAME = DEFAULT_TEMPLATE_FOLDER / "rss.xml.jinja2"
-MKDOCS_LOGGER_NAME = "[RSS-plugin]"
-REMOTE_REQUEST_HEADERS = {
+DEFAULT_CACHE_FOLDER: Path = Path(".cache/plugins/rss")
+DEFAULT_TEMPLATE_FOLDER: Path = Path(__file__).parent / "templates"
+DEFAULT_TEMPLATE_FILENAME: Path = DEFAULT_TEMPLATE_FOLDER / "rss.xml.jinja2"
+MKDOCS_LOGGER_NAME: str = "[RSS-plugin]"
+REMOTE_REQUEST_HEADERS: dict[str, str] = {
     "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
     "User-Agent": f"{__about__.__title__}/{__about__.__version__}",
 }

mkdocs_rss_plugin/git_manager/ci.py

@@ -27,7 +27,14 @@
 
 
 class CiHandler:
-    def __init__(self, repo: Git):
+    """Helper class to handle CI specific warnings."""
+
+    def __init__(self, repo: Git) -> None:
+        """Initialize the CI handler.
+
+        Args:
+            repo (Git): Git repository object
+        """
         self.repo = repo
 
     def raise_ci_warnings(self) -> None:

mkdocs_rss_plugin/models.py

@@ -20,7 +20,7 @@
 
 @dataclass
 class PageInformation:
-    """Data type to set and get page information in order to produce the RSS feed."""
+    """Object describing a page information gathered from Mkdocs and used as feed's item."""
 
     abs_path: Optional[Path] = None
     categories: Optional[list] = None
@@ -37,6 +37,8 @@ class PageInformation:
 
 @dataclass
 class RssFeedBase:
+    """Object describing a feed."""
+
     author: Optional[str] = None
     buildDate: Optional[str] = None
     copyright: Optional[str] = None

mkdocs_rss_plugin/timezoner.py

@@ -38,14 +38,13 @@ def set_datetime_zoneinfo(
 ) -> datetime:
     """Apply timezone to a naive datetime.
 
-    :param input_datetime: offset-naive datetime
-    :type input_datetime: datetime
-    :param config_timezone: name of timezone as registered in IANA database,
-    defaults to "UTC". Example : Europe/Paris.
-    :type config_timezone: str, optional
-
-    :return: offset-aware datetime
-    :rtype: datetime
+    Args:
+        input_datetime (datetime): offset-naive datetime
+        config_timezone (str, optional): name of timezone as registered in IANA
+            database. Defaults to "UTC". Example : Europe/Paris.
+
+    Returns:
+        datetime: offset-aware datetime
     """
     if input_datetime.tzinfo:
         return input_datetime

requirements/documentation.txt

@@ -5,5 +5,5 @@ mkdocs-git-committers-plugin-2>=2.4.1,<2.6
 mkdocs-git-revision-date-localized-plugin>=1.3,<1.4
 mkdocs-material[imaging]>=9.5.47,<10
 mkdocs-minify-plugin>=0.8,<0.9
-mkdocstrings[python]>=0.27,<1
+mkdocstrings-python>=1.16.2,<1.17
 termynal>=0.12.2,<0.13