chore: add changelog and documentation updates

- Created a new `CHANGELOG.md` file to document all notable changes to the project, adhering to the Keep a Changelog format.
- Updated `CONTRIBUTING.md` to include instructions for building and previewing documentation using MkDocs.
- Added `mkdocs.yml` configuration for documentation generation, including navigation structure and theme settings.
- Enhanced various documentation files, including API reference, architecture overview, configuration reference, and runbook, to provide comprehensive guidance for users and developers.
- Included new sections in the README for changelog and documentation links, improving accessibility to project information.

duty_teller/services/group_duty_pin_service.py

@@ -17,7 +17,17 @@ from duty_teller.i18n import t
 
 
 def format_duty_message(duty, user, tz_name: str, lang: str = "en") -> str:
-    """Build the text for the pinned message. duty, user may be None."""
+    """Build the text for the pinned duty message.
+
+    Args:
+        duty: Duty instance or None.
+        user: User instance or None.
+        tz_name: Timezone name for display (e.g. Europe/Moscow).
+        lang: Language code for i18n ('ru' or 'en').
+
+    Returns:
+        Formatted message string; "No duty" if duty or user is None.
+    """
     if duty is None or user is None:
         return t(lang, "duty.no_duty")
     try:
@@ -53,7 +63,16 @@ def format_duty_message(duty, user, tz_name: str, lang: str = "en") -> str:
 
 
 def get_duty_message_text(session: Session, tz_name: str, lang: str = "en") -> str:
-    """Get current duty from DB and return formatted message."""
+    """Get current duty from DB and return formatted message text.
+
+    Args:
+        session: DB session.
+        tz_name: Timezone name for display.
+        lang: Language code for i18n.
+
+    Returns:
+        Formatted duty message or "No duty" if none.
+    """
     now = datetime.now(timezone.utc)
     result = get_current_duty(session, now)
     if result is None:
@@ -63,26 +82,61 @@ def get_duty_message_text(session: Session, tz_name: str, lang: str = "en") -> s
 
 
 def get_next_shift_end_utc(session: Session) -> datetime | None:
-    """Return next shift end as naive UTC datetime for job scheduling."""
+    """Return next shift end as naive UTC datetime for job scheduling.
+
+    Args:
+        session: DB session.
+
+    Returns:
+        Next shift end (naive UTC) or None.
+    """
     return get_next_shift_end(session, datetime.now(timezone.utc))
 
 
 def save_pin(session: Session, chat_id: int, message_id: int) -> None:
-    """Save or update the pinned message record for a chat."""
+    """Save or update the pinned duty message record for a chat.
+
+    Args:
+        session: DB session.
+        chat_id: Telegram chat id.
+        message_id: Message id to store.
+    """
     save_group_duty_pin(session, chat_id, message_id)
 
 
 def delete_pin(session: Session, chat_id: int) -> None:
-    """Remove the pinned message record when the bot leaves the group."""
+    """Remove the pinned message record for the chat (e.g. when bot leaves).
+
+    Args:
+        session: DB session.
+        chat_id: Telegram chat id.
+    """
     delete_group_duty_pin(session, chat_id)
 
 
 def get_message_id(session: Session, chat_id: int) -> int | None:
-    """Return message_id for the pin in this chat, or None."""
+    """Return message_id for the pinned duty message in this chat.
+
+    Args:
+        session: DB session.
+        chat_id: Telegram chat id.
+
+    Returns:
+        Message id or None if no pin record.
+    """
     pin = get_group_duty_pin(session, chat_id)
     return pin.message_id if pin else None
 
 
 def get_all_pin_chat_ids(session: Session) -> list[int]:
-    """Return all chat_ids that have a pinned duty message (for restoring jobs on startup)."""
+    """Return all chat_ids that have a pinned duty message.
+
+    Used to restore update jobs on bot startup.
+
+    Args:
+        session: DB session.
+
+    Returns:
+        List of chat ids.
+    """
     return get_all_group_duty_pin_chat_ids(session)