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.
This commit is contained in:
parent
584904bbf9
commit
f5df515d2b
2 changed files with 106 additions and 1 deletions
101
makesite.py
101
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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue