Add a feature for buuilding docs sitemap on sphinx build

Author: digreatbrian

docs/source/conf.py

@@ -8,8 +8,8 @@
 
 
 # METADATA
-DUCK_HOMEPAGE = "https://duckframework.xyz"
-DUCK_DOCS_URL = "https://docs.duckframework.xyz"
+DUCK_HOMEPAGE = "https://duckframework.com"
+DUCK_DOCS_URL = "https://docs.duckframework.com"
 DUCK_PACKAGE_RELATIVE_PATH = "../../duck"
 
 # Path to the duck package's __init__.py
@@ -24,6 +24,29 @@ def on_html_page_context(app, template_name, template, context, _):
         context["DUCK_HOMEPAGE"] = DUCK_HOMEPAGE
         context["DUCK_DOCS_URL"] = DUCK_DOCS_URL
     app.connect("html-page-context", on_html_page_context)
+    app.connect("build-finished", on_build_finished)
+    
+
+def on_build_finished(app, exception):
+    """
+    Called when Sphinx finishes building the documentation.
+
+    Args:
+        app: The Sphinx application object.
+        exception: Exception raised during build, if any.
+    """
+    from sitemap import generate_sitemap
+    from duck.logging import console
+    
+    if exception is not None:
+        console.log("Build failed, skipping custom post-build task, no sitemap will be generated.", level=console.WARNING)
+        return
+
+    console.log("Build completed successfully. Running post-build task...", level=console.WARNING)
+    
+    # Build the sitemap
+    generate_sitemap()
+  
 
 def read_metadata_from_init(init_path):
     """
@@ -37,6 +60,7 @@ def read_metadata_from_init(init_path):
         dict: A dictionary containing metadata like __version__, __author__, and __email__.
     """
     metadata = {}
+    
     with open(init_path, "r", encoding="utf-8") as f:
         for line in f:
             # Look for __<name>__ = '<value>'
@@ -167,7 +191,7 @@ def read_metadata_from_init(init_path):
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
 html_title = "Duck Framework — Python Web Framework | Build Web Apps Without JavaScript"
-html_baseurl = "https://docs.duckframework.xyz/main/"
+html_baseurl = "https://docs.duckframework.com/main/"
 html_theme_options = {
     "logo_light": "_static/images/duck-logo.png",
     "logo_dark": "_static/images/duck-logo.png",

docs/source/sitemap.py

@@ -0,0 +1,76 @@
+# Retrieve documentation URLs to the sitemap.
+import os
+
+from typing import List
+from pathlib import Path
+
+
+DOCS_URL = "https://docs.duckframework.com"
+DOCS_DIR = Path(__file__).parent.parent
+DOCS_SOURCE_DIRS = ( "source", "source/api")
+
+# Set a testing directory as Duck settings to avoid SettingsError
+os.environ["DUCK_SETTINGS_MODULE"] = "duck.etc.structures.projects.testing.web.settings"
+
+
+def generate_sitemap():
+    """
+    This must be called after sphinx build.
+    
+    The sitemap.xml is placed in `build/html`.
+    """
+    from duck.logging import console
+    from duck.contrib.sitemap import SitemapBuilder
+    
+    urls = set()
+    
+    for source_dir in DOCS_SOURCE_DIRS:
+        try:
+            abs_dir = DOCS_DIR / source_dir
+            for entry in os.scandir(abs_dir):
+                if entry.is_file():
+                    filename = entry.name
+                    docname = None
+                    
+                    if filename == "index.rst":
+                        docname = ""
+                        
+                    elif filename.endswith(".md"):
+                        docname = filename.replace(".md", "")
+                        
+                    elif filename.endswith(".html"):
+                        docname = filename.replace(".html", "")
+                   
+                    elif filename.endswith(".rst"):
+                        docname = filename.replace(".rst", "")
+                        
+                    if source_dir == "source":
+                        # This is the root source directory for main docs.
+                        # Check if docname is set.
+                        if docname is not None:
+                            urls.add(f"{DOCS_URL}/{docname}")
+                    
+                    elif source_dir == "source/api":
+                        # This is the source directory for API docs.
+                        # This directory contains only html files.
+                        # Check if docname is set.
+                        if docname is not None:
+                            urls.add(f"{DOCS_URL}/api/{docname}")
+                    
+                    else:
+                        raise ValueError(f"Unknown source directory '{source_dir}', expected 'source' or 'source/api'.")
+        
+        except FileNotFoundError as e:
+                console.log(f"Caught an error whilst scanning source dirs: {e}", level=console.WARNING)                
+        
+    # Build the sitemap.
+    sitemap_filepath = DOCS_DIR / "build/html/sitemap.xml"
+    builder = SitemapBuilder(
+        server_url=DOCS_URL, # Parsing None will automatically resolve server URL
+        save_to_file=True,
+        filepath=sitemap_filepath,
+        extra_urls=urls,
+    )
+    builder.build()
+    console.log(f"Sitemap has been saved at {sitemap_filepath}", level=console.DEBUG)
+    

duck/utils/email/__init__.py

@@ -81,6 +81,7 @@ def __init__(
         recipients: Optional[List[str]] = None,
         use_bcc: bool = True,
         use_ssl: bool = True,
+        reply_to: Optional[str] = None,
     ):
         """
         Initialize a generic Email instance.
@@ -98,6 +99,7 @@ def __init__(
             recipients: List of additional recipient emails for CC/BCC (optional).
             use_bcc: If True, use BCC for recipients; otherwise, use CC.
             use_ssl: Whether to use SSL for SMTP (default True).
+            reply_to: An email for users to reply to when they hit 'Reply'. Defaults to None, uses default from_addr.
         """
         self.smtp_host = smtp_host
         self.smtp_port = smtp_port
@@ -112,6 +114,7 @@ def __init__(
         self.use_bcc = use_bcc
         self.use_ssl = use_ssl
         self.is_sent = False
+        self.reply_to = reply_to
 
     def _build_message(self) -> Tuple[MIMEMultipart, List[str]]:
         """
@@ -124,7 +127,10 @@ def _build_message(self) -> Tuple[MIMEMultipart, List[str]]:
         msg['From'] = formataddr((self.name, self.from_addr))
         msg['To'] = self.to
         msg['Subject'] = self.subject
-
+        
+        if self.reply_to:
+            msg["Reply-To"] = self.reply_to
+            
         if self.recipients:
             if self.use_bcc:
                 all_recipients = [self.to] + self.recipients