' % item)
newtext = ''
splitted_text = text.splitlines()
@@ -684,19 +686,32 @@ def postProcess(folder, options):
line = line.replace('– ', '– ')
line = line.replace('
', '')
- if line.strip() == '
' or line.strip() == '
':
- next_line = splitted_text[index+1]
- stripline = next_line.strip()
+ if not fn_done and \
+ line.strip() in ('
',
+ '
'):
- # replace the
with a new headline for the first method or first property
- if (stripline == '' or stripline == '' \
- or stripline == '') and not methods_done:
- line = '\n
Methods
\n'
- methods_done = True
+ line = line[8:]
+ fn_done = True
- elif stripline == '' and not properties_done:
- line = '\n
Properties
\n'
- properties_done = True
+ if not methods_done and \
+ line.strip() in ('
',
+ '
',
+ '
',
+ '
'):
+
+ line = '\n
\nMethods
\n' + line[8:]
+ methods_done = True
+
+ if not attr_done and \
+ line.strip() in ('
',
+ '
'):
+
+ line = '\n
\nProperties
\n' + line[8:]
+ attr_done = True
newtext += line + '\n'
diff --git a/sphinxtools/stc_doc_postprocess.py b/sphinxtools/stc_doc_postprocess.py
new file mode 100644
index 00000000..7abfd342
--- /dev/null
+++ b/sphinxtools/stc_doc_postprocess.py
@@ -0,0 +1,256 @@
+# -*- 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()
+
diff --git a/sphinxtools/templates.py b/sphinxtools/templates.py
index 03fbeee8..97832dd6 100644
--- a/sphinxtools/templates.py
+++ b/sphinxtools/templates.py
@@ -60,26 +60,27 @@ TEMPLATE_APPEARANCE = '''
|
-.. figure:: _static/images/widgets/fullsize/wxmsw/%s
- :alt: wxMSW
- :figclass: floatleft
+.. container:: control-appearance-figures
- **wxMSW**
+ .. figure:: _static/images/widgets/fullsize/wxmsw/%s
+ :alt: wxMSW
+ :figclass: appearance-figure
+
+ **wxMSW**
-.. figure:: _static/images/widgets/fullsize/wxmac/%s
- :alt: wxMAC
- :figclass: floatright
+ .. figure:: _static/images/widgets/fullsize/wxmac/%s
+ :alt: wxMAC
+ :figclass: appearance-figure
- **wxMAC**
+ **wxMAC**
-.. figure:: _static/images/widgets/fullsize/wxgtk/%s
- :alt: wxGTK
- :figclass: floatcenter
-
- **wxGTK**
+ .. figure:: _static/images/widgets/fullsize/wxgtk/%s
+ :alt: wxGTK
+ :figclass: appearance-figure
+ **wxGTK**
|
diff --git a/wx/lib/agw/scrolledthumbnail.py b/wx/lib/agw/scrolledthumbnail.py
index 22155816..ce8f187e 100644
--- a/wx/lib/agw/scrolledthumbnail.py
+++ b/wx/lib/agw/scrolledthumbnail.py
@@ -71,7 +71,7 @@ wxWidgets implementation of the :class:`ThumbnailCtrl` control. Andrea Gavana
notes that :class:`ThumbnailCtrl` wouldn't have been so fast and complete
without the suggestions and hints from Peter Damoc.
-Usage:
+Usage
=====
Usage example::
diff --git a/wx/lib/masked/maskededit.py b/wx/lib/masked/maskededit.py
index 87335d42..b99d0543 100644
--- a/wx/lib/masked/maskededit.py
+++ b/wx/lib/masked/maskededit.py
@@ -117,7 +117,7 @@ mask
X Allow string.letters, string.punctuation, string.digits
& Allow string.punctuation only (doesn't include all unicode symbols)
\* Allow any visible character
- | explicit field boundary (takes no space in the control; allows mix
+ \| Explicit field boundary (takes no space in the control; allows mix
of adjacent mask characters to be treated as separate fields,
eg: '&|###' means "field 0 = '&', field 1 = '###'", but there's
no fixed characters in between.
@@ -189,59 +189,67 @@ defaultEncoding
formatcodes
These other properties can be passed to the class when instantiating it:
Formatcodes are specified as a string of single character formatting
- codes that modify behavior of the control::
+ codes that modify behavior of the control:
- _ Allow spaces
- ! Force upper
- ^ Force lower
- R Right-align field(s)
- r Right-insert in field(s) (implies R)
- < Stay in field until explicit navigation out of it
+ ======= ==========================================================
+ _ Allow spaces
+ ! Force upper
+ ^ Force lower
+ R Right-align field(s)
+ r Right-insert in field(s) (implies R)
+ < Stay in field until explicit navigation out of it
- > Allow insert/delete within partially filled fields (as
- opposed to the default "overwrite" mode for fixed-width
- masked edit controls.) This allows single-field controls
- or each field within a multi-field control to optionally
- behave more like standard text controls.
- (See EMAIL or phone number autoformat examples.)
+ > Allow insert/delete within partially filled fields (as
+ opposed to the default "overwrite" mode for fixed-width
+ masked edit controls.) This allows single-field controls
+ or each field within a multi-field control to optionally
+ behave more like standard text controls.
+ (See EMAIL or phone number autoformat examples.)
- *Note: This also governs whether backspace/delete operations
- shift contents of field to right of cursor, or just blank the
- erased section.
+ .. note::
- Also, when combined with 'r', this indicates that the field
- or control allows right insert anywhere within the current
- non-empty value in the field. (Otherwise right-insert behavior
- is only performed to when the entire right-insertable field is
- selected or the cursor is at the right edge of the field.*
+ This also governs whether backspace/delete operations
+ shift contents of field to right of cursor, or just blank
+ the erased section.
+
+ Also, when combined with 'r', this indicates that the field
+ or control allows right insert anywhere within the current
+ non-empty value in the field. (Otherwise right-insert behavior
+ is only performed to when the entire right-insertable field is
+ selected or the cursor is at the right edge of the field.
- , Allow grouping character in integer fields of numeric controls
- and auto-group/regroup digits (if the result fits) when leaving
- such a field. (If specified, .SetValue() will attempt to
- auto-group as well.)
- ',' is also the default grouping character. To change the
- grouping character and/or decimal character, use the groupChar
- and decimalChar parameters, respectively.
- Note: typing the "decimal point" character in such fields will
- clip the value to that left of the cursor for integer
- fields of controls with "integer" or "floating point" masks.
- If the ',' format code is specified, this will also cause the
- resulting digits to be regrouped properly, using the current
- grouping character.
- - Prepend and reserve leading space for sign to mask and allow
- signed values (negative #s shown in red by default.) Can be
- used with argument useParensForNegatives (see below.)
- 0 integer fields get leading zeros
- D Date[/time] field
- T Time field
- F Auto-Fit: the control calculates its size from
- the length of the template mask
- V validate entered chars against validRegex before allowing them
- to be entered vs. being allowed by basic mask and then having
- the resulting value just colored as invalid.
- (See USSTATE autoformat demo for how this can be used.)
- S select entire field when navigating to new field
+ , Allow grouping character in integer fields of numeric controls
+ and auto-group/regroup digits (if the result fits) when leaving
+ such a field. (If specified, .SetValue() will attempt to
+ auto-group as well.)
+ ',' is also the default grouping character. To change the
+ grouping character and/or decimal character, use the groupChar
+ and decimalChar parameters, respectively.
+
+ .. note::
+
+ Typing the "decimal point" character in such fields will
+ clip the value to that left of the cursor for integer
+ fields of controls with "integer" or "floating point" masks.
+
+ If the ',' format code is specified, this will also cause the
+ resulting digits to be regrouped properly, using the current
+ grouping character.
+ \- Prepend and reserve leading space for sign to mask and allow
+ signed values (negative #s shown in red by default.) Can be
+ used with argument useParensForNegatives (see below.)
+ 0 Integer fields get leading zeros
+ D Date[/time] field
+ T Time field
+ F Auto-Fit: the control calculates its size from
+ the length of the template mask
+ V Validate entered chars against validRegex before allowing them
+ to be entered vs. being allowed by basic mask and then having
+ the resulting value just colored as invalid.
+ (See USSTATE autoformat demo for how this can be used.)
+ S Select entire field when navigating to new field
+ ======= ==========================================================
fillChar
diff --git a/wx/lib/masked/numctrl.py b/wx/lib/masked/numctrl.py
index d0177d19..284f7a5a 100644
--- a/wx/lib/masked/numctrl.py
+++ b/wx/lib/masked/numctrl.py
@@ -89,7 +89,7 @@ masked.NumCtrl:
emptyBackgroundColour = "White",
validBackgroundColour = "White",
invalidBackgroundColour = "Yellow",
- autoSize = True
+ autoSize = True,
)
diff --git a/wx/lib/plot/examples/demo.py b/wx/lib/plot/examples/demo.py
index ce1767b1..4bb63437 100644
--- a/wx/lib/plot/examples/demo.py
+++ b/wx/lib/plot/examples/demo.py
@@ -7,10 +7,14 @@
demo.py
=======
-This is a demo showing some of the capabilities of the :mod:`wx.lib.plot`
-package. It is intended to be run as a standalone script via::
+.. highlight:: shell
- user@host:.../site-packages/wx/lib/plot$ python examples/demo.py
+This is a demo showing some of the capabilities of the :mod:`wx.lib.plot`
+package.
+
+It is intended to be run as a standalone script via::
+
+ user@host:.../site-packages/wx/lib/plot$ python examples/demo.py
"""
__docformat__ = "restructuredtext en"
diff --git a/wx/lib/plot/examples/simple_example.py b/wx/lib/plot/examples/simple_example.py
index e8f539c8..b120bfe0 100644
--- a/wx/lib/plot/examples/simple_example.py
+++ b/wx/lib/plot/examples/simple_example.py
@@ -1,10 +1,12 @@
# -*- coding: utf-8 -*-
"""
+.. highlight:: shell
+
A simple example showing how to use lib.plot from wxPython.
It is intended to be run as a standalone script via::
- user@host:.../site-packages/wx/lib/plot$ python examples/simple_example.py
+ user@host:.../site-packages/wx/lib/plot$ python examples/simple_example.py
"""
__docformat__ = "restructuredtext en"
diff --git a/wx/lib/plot/polyobjects.py b/wx/lib/plot/polyobjects.py
index be9ab831..81f5d27b 100644
--- a/wx/lib/plot/polyobjects.py
+++ b/wx/lib/plot/polyobjects.py
@@ -120,7 +120,7 @@ class PolyPoints(object):
:type: tuple of bool, length 2
:raises ValueError: when setting an invalid value
- .. notes::
+ .. note::
This is a simplified example of how SymLog works::
@@ -163,7 +163,7 @@ class PolyPoints(object):
:type: tuple of float, length 2
:raises ValueError: when setting an invalid value
- .. notes::
+ .. note::
This is a simplified example of how SymLog works::
@@ -221,7 +221,7 @@ class PolyPoints(object):
:setter: Sets the value of points.
:type: list of `(x, y)` pairs
- .. Note::
+ .. note::
Only set unscaled points - do not perform the log, abs, or symlog
adjustments yourself.
@@ -1010,17 +1010,10 @@ class PolyBoxPlot(PolyPoints):
outliers are outside of 1.5 * IQR
- Parameters
- ----------
- data : array-like
- The data to plot
-
- Returns
- -------
- bpdata : collections.namedtuple
- Descriptive statistics for data:
+ :param array-like data: The data to plot
+ :return bpdata: Descriptive statistics for data:
(min_data, low_whisker, q25, median, q75, high_whisker, max_data)
-
+ :rtype: collections.namedtuple
"""
data = self._clean_data(data)
@@ -1066,20 +1059,20 @@ class PolyBoxPlot(PolyPoints):
"""
Draws a box plot on the DC.
- Notes
- -----
- The following draw order is required:
+ .. note::
- 1. First the whisker line
- 2. Then the IQR box
- 3. Lasly the median line.
+ The following draw order is required:
- This is because
+ 1. First the whisker line
+ 2. Then the IQR box
+ 3. Lasly the median line.
- + The whiskers are drawn as single line rather than two lines
- + The median line must be visible over the box if the box has a fill.
+ This is because
- Other than that, the draw order can be changed.
+ + The whiskers are drawn as single line rather than two lines
+ + The median line must be visible over the box if the box has a fill.
+
+ Other than that, the draw order can be changed.
"""
self._draw_whisker(dc, printerScale)
self._draw_iqr_box(dc, printerScale)