Fix 'What's New' page formatting and generation (#464)

* Fix 'What's New' page formatting and generation

Improves the RST conversion logic in 'fetch_releases.py' to correctly handle Markdown headers, code blocks, images, and HTML details tags. Also updates 'conf.py' to use 'sys.executable' for robust script execution.

* Switch to m2r2 for Markdown to RST conversion

Replaces custom manual parsing with m2r2 library for more robust Markdown to ReStructuredText conversion in 'fetch_releases.py'. Adds 'm2r2' to 'environment.yml' dependencies.

* Add lxml-html-clean dependency

Fixes ImportError: lxml.html.clean module is now a separate project. This is required by nbsphinx.

Author: cvanelteren

docs/_scripts/fetch_releases.py

@@ -2,9 +2,12 @@
 Dynamically build what's new page based on github releases
 """
 
-import requests, re
+import re
 from pathlib import Path
 
+import requests
+from m2r2 import convert
+
 GITHUB_REPO = "ultraplot/ultraplot"
 OUTPUT_RST = Path("whats_new.rst")
 
@@ -14,21 +17,10 @@
 
 def format_release_body(text):
     """Formats GitHub release notes for better RST readability."""
-    lines = text.strip().split("\n")
-    formatted = []
-
-    for line in lines:
-        line = line.strip()
-
-        # Convert Markdown ## Headers to RST H2
-        if line.startswith("## "):
-            title = line[3:].strip()  # Remove "## " from start
-            formatted.append(f"{title}\n{'~' * len(title)}\n")  # RST H2 Format
-        else:
-            formatted.append(line)
+    # Convert Markdown to RST using m2r2
+    formatted_text = convert(text)
 
     # Convert PR references (remove "by @user in ..." but keep the link)
-    formatted_text = "\n".join(formatted)
     formatted_text = re.sub(
         r" by @\w+ in (https://github.com/[^\s]+)", r" (\1)", formatted_text
     )

docs/conf.py

@@ -12,14 +12,14 @@
 # -- Imports and paths --------------------------------------------------------------
 
 # Import statements
-import os
-import sys
 import datetime
+import os
 import subprocess
-from pathlib import Path
+import sys
 
 # Surpress warnings from cartopy when downloading data inside docs env
 import warnings
+from pathlib import Path
 
 try:
     from cartopy.io import DownloadWarning
@@ -38,6 +38,7 @@
     if not hasattr(sphinx.util, "console"):
         # Create a compatibility layer
         import sys
+
         import sphinx.util
         from sphinx.util import logging
 
@@ -54,7 +55,7 @@ def __getattr__(self, name):
 # Build what's news page from github releases
 from subprocess import run
 
-run("python _scripts/fetch_releases.py".split(), check=False)
+run([sys.executable, "_scripts/fetch_releases.py"], check=False)
 
 # Update path for sphinx-automodapi and sphinxext extension
 sys.path.append(os.path.abspath("."))
@@ -63,7 +64,6 @@ def __getattr__(self, name):
 # Print available system fonts
 from matplotlib.font_manager import fontManager
 
-
 # -- Project information -------------------------------------------------------
 # The basic info
 project = "UltraPlot"

environment.yml

@@ -30,5 +30,7 @@ dependencies:
   - networkx
   - pyarrow
   - cftime
+  - m2r2
+  - lxml-html-clean
   - pip:
       - git+https://github.com/ultraplot/UltraTheme.git