improve(docs): refine docstrings and API page

Guts · Feb 25, 2025 · b188451 · b188451
1 parent 54502d5
commit b188451
Show file tree

Hide file tree

Showing 5 changed files with 41 additions and 19 deletions.
diff --git a/docs/api.md b/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
diff --git a/mkdocs_rss_plugin/constants.py b/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__}",
 }
diff --git a/mkdocs_rss_plugin/git_manager/ci.py b/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:

diff --git a/mkdocs_rss_plugin/models.py b/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

diff --git a/mkdocs_rss_plugin/timezoner.py b/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