Add comprehensive docstrings to all functions

Added Google-style docstrings to all functions and classes in makesite.py and monitor.py with descriptions, argument types, and return values.

makesite.py

@@ -28,7 +28,18 @@ FRENCH_MONTHS = ['janv.', 'févr.', 'mars', 'avr.', 'mai', 'juin',
 
 
 class HighlightRenderer(mistune.HTMLRenderer):
+    """Custom Mistune renderer that adds syntax highlighting to code blocks using Pygments."""
+
     def block_code(self, code, info=None):
+        """Render code blocks with syntax highlighting.
+
+        Args:
+            code: The code content to render
+            info: Optional language identifier for syntax highlighting
+
+        Returns:
+            str: HTML with syntax-highlighted code or plain pre/code tags
+        """
         if info:
             lexer = get_lexer_by_name(info, stripall=True)
             formatter = html.HtmlFormatter()
@@ -171,6 +182,15 @@ def render(template, **params):
 
 
 def get_header_list_value(header_name, page_params):
+    """Extract and parse a space-separated list from a header value.
+
+    Args:
+        header_name: Name of the header to extract (e.g., 'category', 'tag')
+        page_params: Dict containing page parameters
+
+    Returns:
+        list: List of stripped string values from the header
+    """
     header_list = []
     if header_name in page_params:
         for s in page_params[header_name].split(" "):
@@ -266,6 +286,14 @@ def _process_comments(page_params, stacosys_url, comment_layout,
 
 
 def get_friendly_date(date_str):
+    """Convert date string to French-formatted readable date.
+
+    Args:
+        date_str: Date string in YYYY-MM-DD format
+
+    Returns:
+        str: French-formatted date (e.g., "15 janv. 2024")
+    """
     dt = datetime.datetime.strptime(date_str, "%Y-%m-%d")
     french_month = FRENCH_MONTHS[dt.month - 1]
     return f"{dt.day:02d} {french_month} {dt.year}"
@@ -407,7 +435,17 @@ def make_list(
         posts, dst, list_layout, item_layout,
         header_layout, footer_layout, **params
 ):
-    """Generate list page for a blog."""
+    """Generate list page for a blog.
+
+    Args:
+        posts: List of post dictionaries to include in the list
+        dst: Destination path for the generated HTML file
+        list_layout: Template for the overall list page
+        item_layout: Template for individual list items
+        header_layout: Template for page header (None to skip)
+        footer_layout: Template for page footer (None to skip)
+        **params: Additional parameters for template rendering
+    """
 
     # header
     if header_layout is None:
@@ -447,6 +485,16 @@ def make_list(
 
 
 def create_blog(page_layout, list_in_page_layout, params):
+    """Create blog posts and paginated index pages.
+
+    Args:
+        page_layout: Template for individual pages
+        list_in_page_layout: Template for list pages wrapped in page layout
+        params: Global site parameters
+
+    Returns:
+        list: Sorted list of all post dictionaries (newest first)
+    """
     banner_layout = fread("layout/banner.html")
     paging_layout = fread("layout/paging.html")
     post_layout = fread("layout/post.html")
@@ -509,6 +557,14 @@ def create_blog(page_layout, list_in_page_layout, params):
 
 def generate_categories(list_in_page_layout, item_nosummary_layout,
                         posts, params):
+    """Generate category pages grouping posts by category.
+
+    Args:
+        list_in_page_layout: Template for list pages
+        item_nosummary_layout: Template for list items without summaries
+        posts: List of all blog posts
+        params: Global site parameters
+    """
     category_title_layout = fread("layout/category_title.html")
     cat_post = {}
     for post in posts:
@@ -532,6 +588,15 @@ def generate_categories(list_in_page_layout, item_nosummary_layout,
 
 def generate_archives(blog_posts, list_in_page_layout, item_nosummary_layout,
                       archive_title_layout, params):
+    """Generate archives page with all blog posts.
+
+    Args:
+        blog_posts: List of all blog posts
+        list_in_page_layout: Template for list pages
+        item_nosummary_layout: Template for list items without summaries
+        archive_title_layout: Template for archive page header
+        params: Global site parameters
+    """
     make_list(
         blog_posts,
         "_site/archives/index.html",
@@ -545,6 +610,14 @@ def generate_archives(blog_posts, list_in_page_layout, item_nosummary_layout,
 
 def generate_notes(page_layout, archive_title_layout,
                    list_in_page_layout, params):
+    """Generate notes pages and notes index.
+
+    Args:
+        page_layout: Template for individual pages
+        archive_title_layout: Template for notes index header
+        list_in_page_layout: Template for list pages
+        params: Global site parameters
+    """
     note_layout = fread("layout/note.html")
     item_note_layout = fread("layout/item_note.html")
     note_layout = render(page_layout, content=note_layout)
@@ -569,6 +642,12 @@ def generate_notes(page_layout, archive_title_layout,
 
 
 def generate_rss_feeds(posts, params):
+    """Generate RSS feeds: main feed and per-tag feeds.
+
+    Args:
+        posts: List of all blog posts
+        params: Global site parameters
+    """
     rss_xml = fread("layout/rss.xml")
     rss_item_xml = fread("layout/rss_item.xml")
 
@@ -606,6 +685,12 @@ def generate_rss_feeds(posts, params):
 
 
 def generate_sitemap(posts, params):
+    """Generate XML sitemap for all posts.
+
+    Args:
+        posts: List of all blog posts
+        params: Global site parameters
+    """
     sitemap_xml = fread("layout/sitemap.xml")
     sitemap_item_xml = fread("layout/sitemap_item.xml")
     make_list(
@@ -620,6 +705,14 @@ def generate_sitemap(posts, params):
 
 
 def get_params(param_file):
+    """Load site parameters from JSON file with defaults.
+
+    Args:
+        param_file: Path to JSON parameters file
+
+    Returns:
+        dict: Site parameters with defaults and loaded values
+    """
     # Default parameters.
     params = {
         "title": "Blog",
@@ -637,12 +730,18 @@ def get_params(param_file):
 
 
 def clean_site():
+    """Remove existing _site directory and copy static files."""
     if os.path.isdir("_site"):
         shutil.rmtree("_site")
     shutil.copytree("static", "_site")
 
 
 def main(param_file):
+    """Main entry point for static site generation.
+
+    Args:
+        param_file: Path to JSON parameters file
+    """
 
     params = get_params(param_file)
 

monitor.py

@@ -15,6 +15,11 @@ def fread(filename):
 
 
 def get_nb_of_comments():
+    """Fetch the total number of comments from Stacosys API.
+
+    Returns:
+        int: Total comment count, or 0 if request fails
+    """
     req_url = params["stacosys_url"] + "/comments/count"
     query_params = dict(
         token=params["stacosys_token"]
@@ -24,6 +29,7 @@ def get_nb_of_comments():
 
 
 def exit_program():
+    """Exit the program with status code 0."""
     sys.exit(0)