Refactor function names for clarity and accuracy

Renamed functions to better reflect their actual behavior:
- truncate → strip_tags_and_truncate (does both operations)
- fix_relative_links → make_links_absolute (converts, not fixes)
- clean_html_tag → strip_html_tags (more explicit)
- clean_site → rebuild_site_directory (removes and recreates)
- read_headers → parse_headers (parses, not just reads)
- read_content → parse_post_file (full processing pipeline)
- get_nb_of_comments → get_comment_count (removes French abbreviation)

makesite.py

@@ -71,13 +71,13 @@ def log(msg, *args):
     sys.stderr.write(msg.format(*args) + "\n")
 
 
-def truncate(text, words=25):
+def strip_tags_and_truncate(text, words=25):
-    """Remove tags and truncate text to the specified number of words."""
+    """Remove HTML tags and truncate text to the specified number of words."""
     return " ".join(re.sub(r"(?s)<.*?>", " ", text).split()[:words])
 
 
-def read_headers(text):
+def parse_headers(text):
-    """Parse headers in text and yield (key, value, end-index) tuples."""
+    """Parse HTML comment headers and yield (key, value, end-index) tuples."""
     for match in re.finditer(r"\s*<!--\s*(.+?)\s*:\s*(.+?)\s*-->\s*|.+", text):
         if not match.group(1):
             break
@@ -107,8 +107,8 @@ def slugify(value):
     return re.sub(r"[-\s]+", "-", value)
 
 
-def read_content(filename, params):
+def parse_post_file(filename, params):
-    """Read content and metadata from file into a dictionary."""
+    """Parse post file: read, extract metadata, convert markdown, and generate summary."""
     # Read file content.
     text = fread(filename)
 
@@ -119,7 +119,7 @@ def read_content(filename, params):
 
     # Read headers.
     end = 0
-    for key, val, end in read_headers(text):
+    for key, val, end in parse_headers(text):
         content[key] = val
 
     # slugify post title
@@ -132,19 +132,19 @@ def read_content(filename, params):
     if filename.endswith((".md", ".mkd", ".mkdn", ".mdown", ".markdown")):
         summary_index = text.find("<!-- more")
         if summary_index > 0:
-            summary = markdown(clean_html_tag(text[:summary_index]))
+            summary = markdown(strip_html_tags(text[:summary_index]))
         else:
-            summary = truncate(markdown(clean_html_tag(text)))
+            summary = strip_tags_and_truncate(markdown(strip_html_tags(text)))
         clean_text = text.replace("<!-- more -->", "")
         text = markdown(clean_text)
     else:
-        summary = truncate(text)
+        summary = strip_tags_and_truncate(text)
 
     # Update the dictionary with content and RFC 2822 date.
     content.update(
         {
             "content": text,
-            "content_rss": fix_relative_links(params["site_url"], text),
+            "content_rss": make_links_absolute(params["site_url"], text),
             "rfc_2822_date": rfc_2822_format(content["date"]),
             "summary": summary,
         }
@@ -153,16 +153,16 @@ def read_content(filename, params):
     return content
 
 
-def fix_relative_links(site_url, text):
+def make_links_absolute(site_url, text):
-    """Absolute links needed in RSS feed"""
+    """Convert relative links to absolute URLs for RSS feed."""
     # TODO externalize links replacement configuration
     return text \
         .replace("src=\"/images/20", "src=\"" + site_url + "/images/20") \
         .replace("href=\"/20", "href=\"" + site_url + "/20")
 
 
-def clean_html_tag(text):
+def strip_html_tags(text):
-    """Remove HTML tags."""
+    """Remove HTML tags from text."""
     while True:
         original_text = text
         text = re.sub(r"<\w+.*?>", "", text)
@@ -351,7 +351,7 @@ def make_posts(
 
     for posix_path in Path(src).glob(src_pattern):
         src_path = str(posix_path)
-        content = read_content(src_path, params)
+        content = parse_post_file(src_path, params)
 
         # render text / summary for basic fields
         content["content"] = render(content["content"], **params)
@@ -404,7 +404,7 @@ def make_notes(
 
     for posix_path in Path(src).glob(src_pattern):
         src_path = str(posix_path)
-        content = read_content(src_path, params)
+        content = parse_post_file(src_path, params)
 
         # render text / summary for basic fields
         content["content"] = render(content["content"], **params)
@@ -729,8 +729,8 @@ def get_params(param_file):
     return params
 
 
-def clean_site():
+def rebuild_site_directory():
-    """Remove existing _site directory and copy static files."""
+    """Remove existing _site directory and recreate from static files."""
     if os.path.isdir("_site"):
         shutil.rmtree("_site")
     shutil.copytree("static", "_site")
@@ -746,7 +746,7 @@ def main(param_file):
     params = get_params(param_file)
 
     # Create a new _site directory from scratch.
-    clean_site()
+    rebuild_site_directory()
 
     # Load layouts.
     page_layout = fread("layout/page.html")

monitor.py

@@ -14,7 +14,7 @@ def fread(filename):
         return f.read()
 
 
-def get_nb_of_comments():
+def get_comment_count():
     """Fetch the total number of comments from Stacosys API.
 
     Returns:
@@ -45,13 +45,13 @@ if os.path.isfile("params.json"):
     params.update(json.loads(fread("params.json")))
 
 external_check_cmd = params["external_check"]
-initial_count = get_nb_of_comments()
+initial_count = get_comment_count()
 print(f"Comments = {initial_count}")
 while True:
     # check number of comments every 60 seconds
     for _ in range(15):
         time.sleep(60)
-        if initial_count != get_nb_of_comments():
+        if initial_count != get_comment_count():
             exit_program()
     # check if git repo changed every 15 minutes
     if external_check_cmd and os.system(external_check_cmd):