# -*- coding: utf-8 -*- #--------------------------------------------------------------------------- # Name: sphinxtools/stc_doc_postprocess.py # Author: Matthias (neofelis2X) # # Created: 27-Jan-2025 # Copyright: (c) 2010-2025 # License: wxWindows License #--------------------------------------------------------------------------- """ This script postprocesses the ReST documentation file of the wx.stc.StyledTextCtrl class. This class has more than 760 methods, so the 'Method Summary' is sorted into categories. """ import xml.etree.ElementTree as ET from pathlib import Path from buildtools.config import msg from sphinxtools.constants import XMLSRC, SPHINXROOT 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): """ Parses values from an xml file containing categories, method names and occasional additional category descriptions. """ tree = ET.parse(xml_file) root = tree.getroot() method_mapping = {} current_category = "empty" current_pretty = "Empty" description = '' new_header = False for elem in root.iter(): if elem.tag == 'listofallmembers': break if elem.tag == "header" and isinstance(elem.text, str): if "Raw variants" in elem.text: current_category = "Raw Variants" current_pretty = "Raw Variants" else: current_category = elem.text current_pretty = _clean_category_title(current_category) description = '' new_header = True elif elem.tag == "description" and new_header: para = elem.findall("para") description = _parse_description(para) new_header = False elif elem.tag == "name": method_mapping[elem.text] = (current_pretty, description) return method_mapping def _parse_description(para): """ Goes through some extra steps to parse method descriptions from references. """ description = '' if len(para) > 1: txt = para[1].itertext() sect = para[1].findall("simplesect") if len(sect): description = "".join(txt).split('(', maxsplit=1)[0].strip() description = f".. seealso:: :meth:`~wx.stc.StyledTextCtrl.{description}`" else: description = "".join(txt).strip() return description def _parse_stcdoc_segments(file): """ Read the reStructuredText file and split relevant parts into textblocks. """ m_count = 0 # Count the collected methods pretext = '' # All text before the 'Method Summary' parse_pretext = True links = [] # index_links_done = False methods = {} current_method = '' parse_methods = False posttext = '' # All text after the 'Method Summary' parse_posttext = False with open(file, 'r', encoding="utf-8") as f: for line in f: if parse_posttext: posttext += line elif not index_links_done and line.startswith("- `"): # Rewrite index links new_link = line.split('<')[0].strip("-_ `") new_link = _clean_category_title(new_link) pretext += f"- `{new_link}`_\n" links.append(new_link) if "Constructors" in line: awm = "Additional wxPython Methods" pretext += f"- `{awm}`_\n" links.append(awm) elif "Text area methods" in line: index_links_done = True elif line.startswith(":meth:`~wx.stc.StyledTextCtrl."): # Collect all methods from 'Method Summary' m_count += 1 parse_pretext = False parse_methods = True current_method = line[30:].split('`')[0].strip() if not current_method: print("stc_doc_postprocess:: WARNING: Invalid method name") else: methods[current_method] = line elif parse_methods and line.strip() == '|': parse_methods = False parse_posttext = True posttext = '\n' + line elif parse_pretext: if not TBL_SEP.strip() in line: pretext += line # print(f"Debug: Read {m_count} methods from file.") return (pretext, methods, posttext, links) def _methods_to_categories(methods, mapping): """ Find the right category for each method. Around 20 methods are unique in wxPython and will be put into their own group. """ grouped_methods = {} for name, text in methods.items(): if name in ("__init__", "Create"): category = "Constructors and Related Methods" description = '' text = text.replace("Ctor.", '') elif name in mapping: category = mapping[name][0] description = mapping[name][1] else: category = "Additional wxPython Methods" description = "In addition to the standard Scintilla " + \ "functions, wxPython includes the following " + \ "methods to better integrate better with other features." if category in grouped_methods: grouped_methods[category][0].append(text) grouped_methods[category][1] = description else: grouped_methods[category] = [[text, ], ''] if description: grouped_methods[category][1] = description return grouped_methods def _clean_category_title(raw_title): """ Applies proper title case to category titles. """ category_title = raw_title.strip().title().replace("And", "and") category_title = category_title.replace("Wxstyledtextctrl", "wxStyledTextCtrl") category_title = category_title.replace("Wxpython", "wxPython") return category_title def _assemble_method_category(category, cat_methods, cc): """ Assembles all method ReST directives that go into one category. """ group = '' dashline = '-' * len(category) group = f"\n{category}\n{dashline}\n\n" if cat_methods[1]: group += '\n' + cat_methods[1] + '\n\n' group += TBL_SEP for method in cat_methods[0]: cc += 1 group += method group += TBL_SEP + '\n' return group, cc def _output_reordered_doc(pretext, posttext, grouped_methods): """ Writes the formatted ReST to a file. Overwrites the original file. """ m_count = 0 # count the written methods doc = pretext for category, methods in grouped_methods.items(): cat, m_count = _assemble_method_category(category, methods, m_count) doc += cat doc += posttext STC_RST.write_text(doc, encoding="utf-8") # print(f"Debug: Wrote {m_count} methods to new file.") 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__": stc_categorise_methods()