From 1219d1e89626f54d5395fdd6c7b2c01211500e95 Mon Sep 17 00:00:00 2001
From: neofelis2X <m.kneidinger@mailbox.org>
Date: Thu, 27 Feb 2025 18:55:45 +0100
Subject: [PATCH] fixup! Docs: add script that sorts wxStyledTextCtrl into
 categories

---
 build.py                           |  4 ++++
 etg/_stc.py                        |  2 --
 sphinxtools/stc_doc_postprocess.py | 27 ++++++++++++++++++---------
 3 files changed, 22 insertions(+), 11 deletions(-)

diff --git a/build.py b/build.py
index 53033570..442fa28e 100755
--- a/build.py
+++ b/build.py
@@ -1145,6 +1145,7 @@ def cmd_etg(options, args):
 
 def cmd_sphinx(options, args):
     from sphinxtools.postprocess import genIndexes, makeHeadings, postProcess, genGallery
+    from sphinxtools.stc_doc_postprocess import stc_categorise_methods
 
     cmdTimer = CommandTimer('sphinx')
     pwd = pushDir(phoenixDir())
@@ -1158,6 +1159,9 @@ def cmd_sphinx(options, args):
     if not textFiles:
         raise Exception('No documentation files found. Please run "build.py touch etg" first')
 
+    # Sort all wx.stc.StyledTextCtrl methods into categories
+    stc_categorise_methods()
+
     # Copy the rst files into txt files
     restDir = os.path.join(sphinxDir, 'rest_substitutions', 'overviews')
     rstFiles = sorted(glob.glob(restDir + '/*.rst'))
diff --git a/etg/_stc.py b/etg/_stc.py
index 12197e61..bcf8b55f 100644
--- a/etg/_stc.py
+++ b/etg/_stc.py
@@ -9,7 +9,6 @@
 
 import etgtools
 import etgtools.tweaker_tools as tools
-import sphinxtools.stc_doc_postprocess as postprocess
 
 PACKAGE   = "wx"
 MODULE    = "_stc"
@@ -260,7 +259,6 @@ def run():
     #-----------------------------------------------------------------
     tools.doCommonTweaks(module)
     tools.runGenerators(module)
-    postprocess.categorise_methods()
 
 
 
diff --git a/sphinxtools/stc_doc_postprocess.py b/sphinxtools/stc_doc_postprocess.py
index 8ac6ea0c..7abfd342 100644
--- a/sphinxtools/stc_doc_postprocess.py
+++ b/sphinxtools/stc_doc_postprocess.py
@@ -13,18 +13,19 @@ wx.stc.StyledTextCtrl class. This class has more than 760 methods,
 so the 'Method Summary' is sorted into categories.
 """
 
-import os
 import xml.etree.ElementTree as ET
+from pathlib import Path
 
+from buildtools.config import msg
 from sphinxtools.constants import XMLSRC, SPHINXROOT
 
-STC_CLASS_XML = os.path.join(XMLSRC, "classwx_styled_text_ctrl.xml")
-STC_RST = os.path.join(SPHINXROOT, "wx.stc.StyledTextCtrl.txt")
+STC_CLASS_XML = Path(XMLSRC, "classwx_styled_text_ctrl.xml")
+STC_RST = Path(SPHINXROOT, "wx.stc.StyledTextCtrl.txt")
 TBL_SEP = "======================================================" + \
           "========================== ===========================" + \
           "=====================================================\n"
 
-def _parse_method_categories(xml_file: str):
+def _parse_method_categories(xml_file):
     """
     Parses values from an xml file containing categories, method
     names and occasional additional category descriptions.
@@ -83,7 +84,7 @@ def _parse_description(para):
 
     return description
 
-def _parse_stcdoc_segments(file: str):
+def _parse_stcdoc_segments(file):
     """
     Read the reStructuredText file and split relevant parts into textblocks.
     """
@@ -225,23 +226,31 @@ def _output_reordered_doc(pretext, posttext, grouped_methods):
 
     doc += posttext
 
-    with open(STC_RST, 'w', encoding="utf-8") as f:
-        f.write(doc)
+    STC_RST.write_text(doc, encoding="utf-8")
 
     # print(f"Debug: Wrote {m_count} methods to new file.")
 
-def categorise_methods():
+def stc_categorise_methods():
     """
     Loads the ReST file, categorises the method summary and saves a new file. 
     Thr original file is overwritten.
     """
+    if not STC_CLASS_XML.is_file():
+        return msg(f"Warning: StyledTextCtrl post-processing failed: {STC_CLASS_XML.name} not available.")
+
     mapping = _parse_method_categories(STC_CLASS_XML)
+
+    if not STC_RST.is_file():
+        return msg(f"Warning: StyledTextCtrl post-processing failed: {STC_RST.name} not available.")
+
     pre, methods, post, links = _parse_stcdoc_segments(STC_RST)
     grouped_methods = _methods_to_categories(methods, mapping)
     sorted_methods = {key: grouped_methods[key] for key in links}
     _output_reordered_doc(pre, post, sorted_methods)
 
+    return msg("StyledTextCtrl post-processing completed successfully.")
+
 
 if __name__ == "__main__":
-    categorise_methods()
+    stc_categorise_methods()