From e2f853d0e0e60567891cc1627448c36e35710141 Mon Sep 17 00:00:00 2001 From: Robin Dunn Date: Thu, 19 May 2016 21:04:14 -0700 Subject: [PATCH] Put the module docstrings on the module index pages Plus some other changes to start using using the "wx." prefix on names in the docs. (More are still needed but this is a start. --- b | 4 +-- etg/_core.py | 2 +- etgtools/sip_generator.py | 2 +- sphinxtools/constants.py | 30 ++++++++++++++++++++++ sphinxtools/postprocess.py | 51 ++++++++++++++++++++++---------------- sphinxtools/templates.py | 6 +---- sphinxtools/utilities.py | 5 ++++ 7 files changed, 69 insertions(+), 31 deletions(-) diff --git a/b b/b index d7ef1fc7..fc10d4e4 100755 --- a/b +++ b/b @@ -5,11 +5,11 @@ if [ "$OSTYPE" = "cygwin" ]; then PYTHON=`which python.exe` echo $PYTHON - $PYTHON -u build.py "$@" + $PYTHON -u build.py --dev "$@" else PYTHON=`which python` echo $PYTHON - $PYTHON -u build.py "$@" + $PYTHON -u build.py --dev "$@" fi exit $? diff --git a/etg/_core.py b/etg/_core.py index 7db7578e..126db8e4 100644 --- a/etg/_core.py +++ b/etg/_core.py @@ -16,7 +16,7 @@ MODULE = "_core" NAME = "_core" # Base name of the file to generate to for this script DOCSTRING = """\ The classes in this module are the most commonly used classes for wxPython, -which is why they have been made visible in the core ``wx`` namespace. +which is why they have been made visible in the core `wx` namespace. Everything you need for building typical GUI applications is here. """ diff --git a/etgtools/sip_generator.py b/etgtools/sip_generator.py index 864519bd..7479dff9 100644 --- a/etgtools/sip_generator.py +++ b/etgtools/sip_generator.py @@ -87,7 +87,7 @@ class SipWrapperGenerator(generators.WrapperGeneratorBase): if module.name.startswith('_'): doc = '' if module.docstring: - doc = '\n"""\n%s\n"""\n' % module.docstring + doc = '\n"""\n%s"""\n' % module.docstring stream.write("""\ %%Extract(id=pycode%s, order=5) # This file is generated by wxPython's SIP generator. Do not edit by hand. diff --git a/sphinxtools/constants.py b/sphinxtools/constants.py index 9afef81a..303716b2 100644 --- a/sphinxtools/constants.py +++ b/sphinxtools/constants.py @@ -86,6 +86,33 @@ MODULENAME_REPLACE = {'_core' : 'wx.', } NO_MODULE = { + # -- core -- # + 'AlphaPixelData' : 'wx.', + 'AlphaPixelData_Accessor' : 'wx.', + 'ButtonLabel' : 'wx.', + 'CallLater' : 'wx.', + 'ChildrenRepositioningGuard': 'wx.', + 'GenericDragImage' : 'wx.', + 'GenericMessageDialog' : 'wx.', + 'HSVValue' : 'wx.', + 'MessageParameters' : 'wx.', + 'NativePixelData' : 'wx.', + 'NativePixelData_Accessor' : 'wx.', + 'PixelDataBase' : 'wx.', + 'PyApp' : 'wx.', + 'PyCommandEvent' : 'wx.', + 'PyEvent' : 'wx.', + 'PyEventBinder' : 'wx.', + 'PyOnDemandOutputWindow' : 'wx.', + 'PySimpleApp' : 'wx.', + 'PySingleChoiceDialog' : 'wx.', + 'RGBValue' : 'wx.', + 'ScrolledCanvas' : 'wx.', + 'ScrolledWindow' : 'wx.', + 'TimeZone' : 'wx.', + 'Tm' : 'wx.', + 'WindowBase' : 'wx.', + # -- wxAdvanced -- # # Widgets 'DatePickerCtrlGeneric': 'wx.adv.', @@ -150,6 +177,9 @@ NO_MODULE = { # Enums/constants 'XmlResourceFlags' : 'wx.xrc.', + + # -- wx.msw -- # + 'PyAxBaseWindow' : 'wx.msw', } # Other C++ specific things to strip away diff --git a/sphinxtools/postprocess.py b/sphinxtools/postprocess.py index c5bf9c3c..ffe9dbe2 100644 --- a/sphinxtools/postprocess.py +++ b/sphinxtools/postprocess.py @@ -15,12 +15,6 @@ import sys import re import glob import random -import subprocess - -if sys.version_info < (3,): - import cPickle as pickle -else: - import pickle # Phoenix-specific imports from buildtools.config import copyIfNewer, writeIfChanged, newer, getVcsRev, textfile_open @@ -29,6 +23,9 @@ from . import templates from .utilities import Wx2Sphinx, PickleFile from .constants import HTML_REPLACE, TODAY, SPHINXROOT, SECTIONS_EXCLUDE from .constants import CONSTANT_INSTANCES, WIDGETS_IMAGES_ROOT, SPHINX_IMAGES_ROOT +from .constants import DOCSTRING_KEY + +# ----------------------------------------------------------------------- # def MakeHeadings(): @@ -367,11 +364,11 @@ def ReformatFunctions(file): pf = PickleFile(file) functions = pf.read() - if local_file.count('.') == 1: + if local_file.count('.') == 2: # Core functions - label = 'Core' + label = 'wx Core' else: - label = local_file.split('.')[0:-2][0] + label = '.'.join(local_file.split('.')[0:2]) names = list(functions.keys()) names = [name.lower() for name in names] @@ -420,16 +417,26 @@ def MakeClassIndex(sphinxDir, file): pf = PickleFile(file) classes = pf.read() - # Core functions - label = 'Core' - module = '' - enumDots = 1 - else: - label = local_file.split('.')[0:-2][0] - module = label - enumDots = 2 + module_docstring = classes.get(DOCSTRING_KEY) + if module_docstring is not None: + del classes[DOCSTRING_KEY] + + if local_file.startswith('wx.1'): + # Core functions + label = 'wx Core' + module = 'wx' + enumDots = 2 + # Take care to get only files starting with "wx.UpperName", not + # "wx.lower.UpperName". This is so we don't put all the enums in the + # submodules in the core wx module too. + # TODO: This may not work on case-insensitive file systems, check it. + enum_files = glob.glob(sphinxDir + '/wx.[A-Z]*.enumeration.txt') + else: + label = '.'.join(local_file.split('.')[0:2]) + module = label + enumDots = 3 + enum_files = glob.glob(sphinxDir + '/%s*.enumeration.txt' % module) - enum_files = glob.glob(sphinxDir + '/%s*.enumeration.txt'%module) enum_base = [os.path.split(os.path.splitext(enum)[0])[1] for enum in enum_files] names = list(classes.keys()) @@ -437,19 +444,19 @@ def MakeClassIndex(sphinxDir, file): text = '' if module: - text += '\n\n.. module:: %s\n\n'%module + text += '\n\n.. module:: %s\n\n' % module - text += templates.TEMPLATE_CLASS_INDEX % (label, label) + text += templates.TEMPLATE_CLASS_INDEX % (label, module_docstring) text += 80*'=' + ' ' + 80*'=' + '\n' - text += '%-80s **Short Description**\n'%'**Class**' + text += '%-80s **Short Description**\n' % '**Class**' text += 80*'=' + ' ' + 80*'=' + '\n' for cls in names: out = classes[cls] if '=====' in out: out = '' - text += '%-80s %s\n'%(':ref:`%s`'%Wx2Sphinx(cls)[1], out) + text += '%-80s %s\n' % (':ref:`%s`' % Wx2Sphinx(cls)[1], out) text += 80*'=' + ' ' + 80*'=' + '\n\n' diff --git a/sphinxtools/templates.py b/sphinxtools/templates.py index 0147b4cf..bc7016ff 100644 --- a/sphinxtools/templates.py +++ b/sphinxtools/templates.py @@ -171,15 +171,11 @@ TEMPLATE_CLASS_INDEX = ''' **%s** Classes ========================================================================= -This is an alphabetical listing of all the classes defined in the **%s** module, together with a brief description of them (if available). - -You can look up a class using the alphabetical listing of them. - +%s Class Summary ============= - ''' diff --git a/sphinxtools/utilities.py b/sphinxtools/utilities.py index 885cdb92..af47b6e6 100644 --- a/sphinxtools/utilities.py +++ b/sphinxtools/utilities.py @@ -693,6 +693,11 @@ def PickleClassInfo(class_name, element, short_description): # ----------------------------------------------------------------------- # +# TODO: It would be nice to handle tracking the modules in a better way that +# doesn't need to import and use the ITEMS list in etg files. There are too +# many items added on the fly to try and keep track of them separately. We +# can add the module name to the saved data while in the etg/generator stage. + global ALL_ITEMS ALL_ITEMS = {}