Lerking/Phoenix
1
0
Fork 0
mirror of https://github.com/wxWidgets/Phoenix.git synced 2026-01-05 03:20:08 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

Lots more docs changes.

Browse Source 
Add a generator that updates a persistent mapping of item (functions, classes, etc.) to the module names they are a member of.

Remove the NO_MODULE dictionary as we're tracking all the item --> module names now.

Consolidate the 2 removeWxPrefix implementations to just one.

Fix taking out too much space in the class index when removing the :ref: for unknown items, which caused ReST problems.

Use pyName if it is set

When renaming classes we also need to change the className in the method objects

Properly deal with nested classes
This commit is contained in:
Robin Dunn
2016-05-22 23:39:40 -07:00
parent 7d69bda471
commit 24e2b78806
19 changed files with 4486 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
TODO.rst
View File

@@ -174,10 +174,10 @@ Other Dev Stuff
bytes objects, they should probably be string objects. Or not, sip's
default might be best... See ModuleDef.addGlobalStr if I change my mind.
* If a function or method has overloads but all but one all ignored then the doc
generator should not use the "*args, **kw" form of output and just use the
args string of the remaining function or method definition like for those
that do not have overloads. For example, see Window.GetClientSize
* If a function or method has overloads but all but one all ignored then the
doc generator should not use the "\*args, \*\*kw" form of output and just use
the args string of the remaining function or method definition like for
those that do not have overloads. For example, see Window.GetClientSize
* Check gui_scripts entry points.

5
docs/sphinx/conf.py
View File

@@ -12,6 +12,7 @@
# serve to show the default.
import sys, os
from datetime import datetime
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -46,8 +47,8 @@ availability_all_availabilities = True
master_doc = 'index'
# General information about the project.
project = u'wxPython (Phoenix)'
copyright = u'2012-2016, The wxPython Team'
project = u'wxPython Phoenix'
copyright = u'2012-{}, The wxPython Team'.format(datetime.now().year)
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the

4149
docs/sphinx/itemToModuleMap.json Normal file
View File

File diff suppressed because it is too large Load Diff

42
docs/sphinx/rest_substitutions/overviews/index.rst
View File

@@ -139,8 +139,8 @@ The new wxPython API documentation is available `here <main.html>`_.
MigrationGuide
TODO
DocstringsGuidelines
functions
1classindex
wx.functions
wx.1classindex
app_overview
bitmap_overview
bookctrl_overview
@@ -178,24 +178,26 @@ The new wxPython API documentation is available `here <main.html>`_.
window_ids_overview
window_sizing_overview
window_styles_overview
adv.1classindex
adv.functions
dataview.1classindex
glcanvas.1classindex
grid.1classindex
html.1classindex
html.functions
html2.1classindex
richtext.1classindex
richtext.functions
stc.1classindex
webkit.1classindex
xml.1classindex
xrc.1classindex
xrc.functions
lib
py
tools
wx.adv.1classindex
wx.adv.functions
wx.dataview.1classindex
wx.glcanvas.1classindex
wx.grid.1classindex
wx.html.1classindex
wx.html.functions
wx.html2.1classindex
wx.richtext.1classindex
wx.richtext.functions
wx.stc.1classindex
wx.webkit.1classindex
wx.xml.1classindex
wx.xrc.1classindex
wx.xrc.functions
wx.media.1classindex
wx.msw.1classindex
wx.lib
wx.py
wx.tools
Indices and tables

2
docs/sphinx/rest_substitutions/snippets/python/converted/wx.PlatformInfo.1.py → docs/sphinx/rest_substitutions/snippets/python/converted/wx.PlatformInformation.1.py
View File

@@ -1,2 +1,2 @@
wx.LogMessage("This application is running under %s." % wx.PlatformInfo.Get().GetOperatingSystemIdName())
wx.LogMessage("This application is running under %s." % wx.PlatformInformation.Get().GetOperatingSystemIdName())

2
etg/_core.py
View File

@@ -313,7 +313,7 @@ def run():
A convenience class for :class:`Timer`, that calls the given callable
object once after the given amount of milliseconds, passing any
positional or keyword args. The return value of the callable is
availbale after it has been run with the :meth:`~CallLater.GetResult` method.
available after it has been run with the :meth:`~CallLater.GetResult` method.
If you don't need to get the return value or restart the timer
then there is no need to hold a reference to this object. It will

7
etg/choicdlg.py
View File

@@ -35,13 +35,12 @@ def run():
c = module.find('wxMultiChoiceDialog')
assert isinstance(c, etgtools.ClassDef)
tools.fixTopLevelWindowClass(c)
c = module.find('wxSingleChoiceDialog')
tools.fixTopLevelWindowClass(c)
# Make a new class so we can ignore the clientData parameter in the
# Make a new class so we can ignore the clientData parameter in the ctor
c.addHeaderCode("""\
class wxPySingleChoiceDialog : public wxSingleChoiceDialog {
public:
@@ -59,7 +58,7 @@ def run():
for item in c.allItems():
if item.name == 'wxSingleChoiceDialog':
item.name = 'wxPySingleChoiceDialog'
c.pyName = 'SingleChoiceDialog'
c.renameClass('SingleChoiceDialog')
# ignore this ctor
c.find('wxPySingleChoiceDialog').findOverload('int n').ignore()

7
etg/geometry.py
View File

@@ -32,8 +32,7 @@ def run():
#-----------------------------------------------------------------
# Tweak the parsed meta objects in the module object as needed for
# customizing the generated code and docstrings.
module.addHeaderCode('#include <wx/wx.h>')
@@ -41,7 +40,7 @@ def run():
# wxPoint2D and wxRect2D tweaks
c = module.find('wxPoint2DDouble')
c.pyName = 'Point2D'
c.renameClass('Point2D')
c.find('wxPoint2DDouble').findOverload('wxPoint2DInt').ignore()
c.find('m_x').pyName = 'x'
@@ -95,7 +94,7 @@ def run():
c = module.find('wxRect2DDouble')
c.pyName = 'Rect2D'
c.renameClass('Rect2D')
c.find('m_x').pyName = 'x'
c.find('m_y').pyName = 'y'
c.find('m_width').pyName = 'width'

2
etg/object.py
View File

@@ -58,7 +58,7 @@ def run():
c.find('IsKindOf').ignore()
# EXPERIMENTAL: By turning off the virtualness of the wxObject dtor, and
# since there are no other virutals that we are exposing here, then all
# since there are no other virtuals that we are exposing here, then all
# classes that derive from wxObject that do not have any virtuals of
# their own (or have the virtual flags turned off by the tweaker code)
# can have simpler wrappers generated for them with no extra derived

2
etg/platinfo.py
View File

@@ -37,7 +37,7 @@ def run():
assert isinstance(c, etgtools.ClassDef)
# to avoid conflicts with wxPython's wx.PlatformInfo
c.pyName = 'PlatformInformation'
c.renameClass('PlatformInformation')
c.find('GetEndianness').findOverload('end').ignore()
c.find('GetArchName').findOverload('arch').ignore()

14
etgtools/extractors.py
View File

@@ -629,7 +629,8 @@ class ClassDef(BaseDef):
self.allowNone = False # Allow the convertFrom code to handle None too.
self.instanceCode = None # Code to be used to create new instances of this class
self.innerclasses = []
self.isInner = False
self.isInner = False # Is this a nested class?
self.klass = None # if so, then this is the outer class
# Stuff that needs to be generated after the class instead of within
# it. Some back-end generators need to put stuff inside the class, and
@@ -643,8 +644,16 @@ class ClassDef(BaseDef):
self.extract(element)
def findHierarchy(self, element, all_classes, specials, read):
def renameClass(self, newName):
self.pyName = newName
for item in self.items:
if hasattr(item, 'className'):
item.className = newName
for overload in item.overloads:
overload.className = newName
def findHierarchy(self, element, all_classes, specials, read):
from etgtools import XMLSRC
if not read:
@@ -706,6 +715,7 @@ class ClassDef(BaseDef):
item = ClassDef(innerclass, kind)
item.protection = node.get('prot')
item.isInner = True
item.klass = self # This makes a reference cycle but it's okay
self.innerclasses.append(item)

3
etgtools/generators.py
View File

@@ -13,6 +13,8 @@ Just some base classes and stubs for the various generators
import sys
#---------------------------------------------------------------------------
class WrapperGeneratorBase(object):
def __init__(self):
pass
@@ -120,3 +122,4 @@ def textfile_open(filename, mode='rt'):
#---------------------------------------------------------------------------

125
etgtools/item_module_map.py Normal file
View File

@@ -0,0 +1,125 @@
# -*- coding: utf-8 -*-
# ---------------------------------------------------------------------------
# Name: etgtools/map_generator.py
# Author: Robin Dunn
#
# Created: 20-May-2016
# Copyright: (c) 2016 by Total Control Software
# License: wxWindows License
# ---------------------------------------------------------------------------
"""
This module provides a class that manages a persistent mapping, currently just
for mapping module item names to the name of their module, so other phases of
the code generation can find things that may not have been seen yet. This
class can easily be adapted to other purposes however, if the need arises.
"""
# Standard library imports
import os.path as op
import json
# Phoenix imports
from .generators import textfile_open
from sphinxtools.constants import SPHINXROOT
# ---------------------------------------------------------------------------
class ItemModuleMap(object):
"""
A persistent (across builds) mapping. It manages the data in a
dictionary, and also has a few methods to make the object quack a little
like a real dictionary.
"""
# This is the Borg pattern, so all instances of this class actually share
# the same data attributes
__shared_state = dict(_haveReadData=False,
_items=dict())
def __init__(self):
self.__dict__ = self.__shared_state # Borg part 2
self.fileName = op.join(SPHINXROOT, 'itemToModuleMap.json')
@property
def items(self):
# lazy load the items on first use
if not self._haveReadData:
self.read()
return self._items
# Methods for reading/writing the data from/to persistent storage.
def read(self):
if op.isfile(self.fileName):
with textfile_open(self.fileName, 'rt') as fid:
items = json.load(fid)
# TODO: catch JSON exception...
if items is None:
items = dict()
else:
items = dict()
self._items.clear()
self._items.update(items)
self._haveReadData = True
def flush(self):
with textfile_open(self.fileName, 'wt') as fid:
# Dump the data to a file in json, using a format that minimizes
# excess whitespace.
json.dump(self._items, fid, sort_keys=True,
indent=0, separators=(',', ':'))
def reset(self):
self._haveReadData = False,
self._items.clear()
def get_module(self, name):
return self.items.get(name)
def get_fullname(self, name):
module = self.items.get(name)
if not module:
import mydbstub
return name
return module + name
# Methods for a dictionary Facade, for convenience
def get(self, key, default=None):
return self.items.get(key, default)
def clear(self):
self.items.clear()
def __len__(self):
return len(self.items)
def __getitem__(self, key):
if key in self.items:
return self.items[key]
raise KeyError(key)
def __setitem__(self, key, item):
self.items[key] = item
def __delitem__(self, key):
del self.items[key]
def __iter__(self):
return iter(self.items)
def __contains__(self, key):
return key in self.items
# ---------------------------------------------------------------------------

77
etgtools/map_generator.py Normal file
View File

@@ -0,0 +1,77 @@
# -*- coding: utf-8 -*-
# ---------------------------------------------------------------------------
# Name: etgtools/map_generator.py
# Author: Robin Dunn
#
# Created: 20-May-2016
# Copyright: (c) 2016 by Total Control Software
# License: wxWindows License
# ---------------------------------------------------------------------------
"""
This generator simply maintains a persistent map of top-level item names and
the module each is in. This will be used in the Sphinx generator and will
perhaps help simplify other generator tasks as well.
"""
# Phoenix-specific imports
from . import extractors
from . import generators
from .tweaker_tools import removeWxPrefix
from .item_module_map import ItemModuleMap
from sphinxtools.constants import MODULENAME_REPLACE
# ---------------------------------------------------------------------------
class ItemMapGenerator(generators.DocsGeneratorBase):
def __init__(self):
super(ItemMapGenerator, self).__init__()
def generate(self, module):
assert isinstance(module, extractors.ModuleDef)
realModuleName = MODULENAME_REPLACE[module.module]
imm = ItemModuleMap()
for item in module.items:
name = self._getName(item)
if not name or name.startswith('@'):
continue
if isinstance(item, extractors.ClassDef):
for inner in item.innerclasses:
self.generateInnerClass(inner, imm,
'{}{}.'.format(realModuleName, name))
# TODO: Maybe nested enums too?
# save the module that the name belongs to
imm[name] = realModuleName
# We don't need it currently, but this is how to also store the
# reverse relationships in the same mapping.
#mod_list = imm.get(realModuleName)
#if mod_list is None:
# mod_list = imm[realModuleName] = list()
#if name not in mod_list:
# mod_list.append(name)
# mod_list.sort()
imm.flush()
def generateInnerClass(self, klass, imm, scopeName):
# Recursively handle any inner classes that may be defined, adding the
# enclosing scope as we go to the module name
name = self._getName(klass)
imm[name] = scopeName
for inner in klass.innerclasses:
self.generateInnerClass(inner, imm, '{}{}.'.format(scopeName, name))
def _getName(self, item):
return item.pyName if item.pyName else removeWxPrefix(item.name)
# ---------------------------------------------------------------------------

121
etgtools/sphinx_generator.py
View File

@@ -21,15 +21,11 @@ import operator
import sys
import shutil
import textwrap
import glob
if sys.version_info < (3, ):
from StringIO import StringIO
string_base = basestring
else:
from io import StringIO
string_base = str
@@ -38,15 +34,16 @@ import xml.etree.ElementTree as et
# Phoenix-specific stuff
import etgtools.extractors as extractors
import etgtools.generators as generators
from etgtools.item_module_map import ItemModuleMap
from etgtools.tweaker_tools import removeWxPrefix
# Sphinx-Phoenix specific stuff
from sphinxtools.inheritance import InheritanceDiagram
from sphinxtools import templates
from sphinxtools.utilities import ODict
from sphinxtools.utilities import convertToPython
from sphinxtools.utilities import removeWxPrefix, writeSphinxOutput
from sphinxtools.utilities import writeSphinxOutput
from sphinxtools.utilities import findControlImages, makeSummary, pickleItem
from sphinxtools.utilities import chopDescription, pythonizeType, wx2Sphinx
from sphinxtools.utilities import pickleClassInfo, isNumeric
@@ -56,7 +53,7 @@ from sphinxtools.utilities import PickleFile
from sphinxtools.constants import VERSION, REMOVED_LINKS, SECTIONS
from sphinxtools.constants import MAGIC_METHODS, MODULENAME_REPLACE
from sphinxtools.constants import IGNORE, NO_MODULE
from sphinxtools.constants import IGNORE
from sphinxtools.constants import SPHINXROOT, DOXYROOT
from sphinxtools.constants import SNIPPETROOT, TABLEROOT, OVERVIEW_IMAGES_ROOT
from sphinxtools.constants import DOCSTRING_KEY
@@ -581,8 +578,7 @@ class ParameterList(Node):
if isinstance(xml_item, (extractors.PyFunctionDef, extractors.CppMethodDef)):
return
name = xml_item.name or xml_item.pyName
name = removeWxPrefix(name)
name = xml_item.pyName if xml_item.pyName else removeWxPrefix(xml_item.name)
parent = self.GetTopLevelParent()
is_overload = parent.is_overload if parent else False
@@ -1613,17 +1609,20 @@ class XRef(Node):
if '(' in stripped:
stripped = stripped[0:stripped.index('(')].strip()
if stripped in NO_MODULE:
text = ':ref:`%s`'%(NO_MODULE[stripped] + stripped)
imm = ItemModuleMap()
if stripped in imm:
text = ':ref:`%s`' % (imm.get_fullname(stripped))
else:
if '.' not in stripped:
klass = self.IsClassDescription()
if klass:
text = ':meth:`~%s.%s`'%(klass, stripped)
text = ':meth:`~%s.%s`' % (klass, stripped)
else:
text = ':meth:`%s` '%stripped
text = ':meth:`%s` ' % stripped
else:
text = ':meth:`%s` '%stripped
scope, item_name = stripped.split('.', 1)
scope = wx2Sphinx(scope)[1]
text = ':meth:`%s.%s` ' % (scope, item_name)
else:
text = ':ref:`%s`' % wx2Sphinx(stripped)[1]
@@ -1956,7 +1955,8 @@ class XMLDocString(object):
elif isinstance(xml_item, (extractors.ClassDef, extractors.PyClassDef, extractors.TypedefDef)):
self.kind = 'class'
self.appearance = findControlImages(xml_item)
self.class_name = removeWxPrefix(xml_item.name) or xml_item.pyName
self.class_name = xml_item.pyName if xml_item.pyName else removeWxPrefix(xml_item.name)
self.isInner = getattr(xml_item, 'isInner', False)
elif isinstance(xml_item, extractors.EnumDef):
self.kind = 'enum'
else:
@@ -2214,38 +2214,30 @@ class XMLDocString(object):
:rtype: `string`
"""
imm = ItemModuleMap()
if self.kind == 'class':
klass = self.xml_item
name = removeWxPrefix(klass.name) or klass.pyName
dummy, fullname = wx2Sphinx(name)
name = klass.pyName if klass.pyName else removeWxPrefix(klass.name)
fullname = imm.get_fullname(name)
elif self.kind == 'method':
method = self.xml_item
if hasattr(method, 'isCtor') and method.isCtor:
method_name = '__init__'
if hasattr(method, 'className') and method.className is not None:
klass = removeWxPrefix(method.className)
else:
klass = removeWxPrefix(method.klass.name)
method_name = '%s.%s'%(klass, method_name)
else:
method_name = method.name or method.pyName
if hasattr(method, 'className') and method.className is not None:
klass = removeWxPrefix(method.className)
method_name = '%s.%s'%(klass, method_name)
elif hasattr(method, 'klass'):
klass = removeWxPrefix(method.klass.name)
method_name = '%s.%s'%(klass, method_name)
else:
method_name = removeWxPrefix(method_name)
method_name = '%s'%method_name
klass = None
method_name = method.pyName if method.pyName else method.name
if hasattr(method, 'className') and method.className is not None:
klass = removeWxPrefix(method.className)
else:
klass = method.klass.pyName if method.klass.pyName else removeWxPrefix(method.klass.name)
fullname = '%s.%s' % (imm.get_fullname(klass), method_name)
dummy, fullname = wx2Sphinx(method_name)
elif self.kind == 'function':
function = self.xml_item
name = function.pyName or function.name
name = function.pyName if function.pyName else function.name
fullname = self.current_module + 'functions.%s'%name
if not fullname.strip():
@@ -2481,7 +2473,7 @@ class XMLDocString(object):
elif self.kind == 'function':
function = self.xml_item
name = function.name or function.pyName
name = function.pyName if function.pyName else function.name
name = removeWxPrefix(name)
if function.overloads and not self.is_overload:
@@ -2541,14 +2533,15 @@ class XMLDocString(object):
for ret in return_section:
stripped = ret.strip()
if stripped in NO_MODULE:
ret = NO_MODULE[stripped] + stripped
new_section.append(':ref:`%s`'%ret)
imm = ItemModuleMap()
if stripped in imm:
ret = imm[stripped] + stripped
new_section.append(':ref:`%s`' % ret)
else:
if ret[0].isupper():
new_section.append(':ref:`%s`'%stripped)
new_section.append(':ref:`%s`' % stripped)
else:
new_section.append('`%s`'%stripped)
new_section.append('`%s`' % stripped)
element = et.Element('return', kind='return')
element.text = '( %s )'%(', '.join(new_section))
@@ -2591,7 +2584,7 @@ class XMLDocString(object):
stream = StringIO()
method = self.xml_item
name = method.name or method.pyName
name = method.pyName if method.pyName else method.name
name = removeWxPrefix(name)
if self.is_overload:
@@ -2870,7 +2863,6 @@ class XMLDocString(object):
if self.kind == 'class':
desc = chopDescription(docstrings)
self.short_description = desc
class_name = self.class_name.lower()
pickleItem(desc, self.current_module, self.class_name, 'class')
if self.overloads:
@@ -2896,7 +2888,6 @@ class XMLDocString(object):
class SphinxGenerator(generators.DocsGeneratorBase):
def generate(self, module):
self.current_module = MODULENAME_REPLACE[module.module]
self.module_name = module.name
self.current_class = None
@@ -3091,7 +3082,8 @@ class SphinxGenerator(generators.DocsGeneratorBase):
def generatePyProperty(self, prop):
name = removeWxPrefix(self.current_class.name) or self.current_class.pyName
c = self.current_class
name = c.pyName if c.pyName else removeWxPrefix(c.name)
getter_setter = self.createPropertyLinks(name, prop)
stream = StringIO()
@@ -3111,15 +3103,14 @@ class SphinxGenerator(generators.DocsGeneratorBase):
if klass.ignored:
return
imm = ItemModuleMap()
# generate nested classes
for item in klass.innerclasses:
self.generateClass(item)
name = removeWxPrefix(klass.name) or klass.pyName
## # Hack for App/PyApp...
## if name == 'PyApp':
## klass.name = name = 'App'
name = klass.pyName if klass.pyName else removeWxPrefix(klass.name)
fullname = imm.get_fullname(name)
klass.module = self.current_module
self.current_class = klass
@@ -3174,13 +3165,14 @@ class SphinxGenerator(generators.DocsGeneratorBase):
docstring = XMLDocString(klass)
filename = self.current_module + "%s.txt"%name
#filename = self.current_module + "%s.txt"%name
filename = "%s.txt" % imm.get_fullname(name)
docstring.output_file = filename
docstring.current_module = self.current_module
docstring.Dump()
pickleClassInfo(self.current_module + name, self.current_class, docstring.short_description)
pickleClassInfo(fullname, self.current_class, docstring.short_description)
for item in ctors:
if item.isCtor:
@@ -3203,8 +3195,9 @@ class SphinxGenerator(generators.DocsGeneratorBase):
if isinstance(method, extractors.PyFunctionDef):
self.unIndent(method)
class_name = removeWxPrefix(self.current_class.name) or self.current_class.pyName
c = self.current_class
class_name = c.pyName if c.pyName else removeWxPrefix(c.name)
# docstring
method.name = name
@@ -3212,8 +3205,7 @@ class SphinxGenerator(generators.DocsGeneratorBase):
docstring = XMLDocString(method)
docstring.kind = 'method'
name = removeWxPrefix(self.current_class.name) or self.current_class.pyName
filename = self.current_module + "%s.txt"%class_name
filename = self.current_module + "%s.txt" % class_name
docstring.output_file = filename
docstring.class_name = class_name
@@ -3276,7 +3268,8 @@ class SphinxGenerator(generators.DocsGeneratorBase):
text = '%s %s\n%s%s\n\n'%(' .. deprecated::', VERSION, ' '*9, pm.deprecated.replace('\n', ' '))
stream.write(text)
name = removeWxPrefix(self.current_class.name) or self.current_class.pyName
c = self.current_class
name = c.pyName if c.pyName else removeWxPrefix(c.name)
filename = self.current_module + "%s.txt"%name
writeSphinxOutput(stream, filename, append=True)
@@ -3295,7 +3288,8 @@ class SphinxGenerator(generators.DocsGeneratorBase):
if prop.ignored:
return
name = removeWxPrefix(self.current_class.name) or self.current_class.pyName
c = self.current_class
name = c.pyName if c.pyName else removeWxPrefix(c.name)
getter_setter = self.createPropertyLinks(name, prop)
@@ -3357,7 +3351,7 @@ class SphinxGenerator(generators.DocsGeneratorBase):
if typedef.ignored or not typedef.docAsClass:
return
name = removeWxPrefix(typedef.name) or typedef.pyName
name = typedef.pyName if typedef.pyName else removeWxPrefix(typedef.name)
typedef.module = self.current_module
all_classes = {}
@@ -3442,8 +3436,9 @@ class SphinxGenerator(generators.DocsGeneratorBase):
for ret in return_section:
stripped = ret.strip()
if stripped in NO_MODULE:
ret = NO_MODULE[stripped] + stripped
imm = ItemModuleMap()
if stripped in imm:
ret = imm[stripped] + stripped
new_section.append(':ref:`%s`'%ret)
else:
if ret[0].isupper():

12
etgtools/tweaker_tools.py
View File

@@ -40,7 +40,7 @@ def removeWxPrefixes(node):
"""
Rename items with a 'wx' prefix to not have the prefix. If the back-end
generator supports auto-renaming then it can ignore the pyName value for
those that are changed here. We'll still change them all incase the
those that are changed here. We'll still change them all in case the
pyNames are needed elsewhere.
"""
for item in node.allItems():
@@ -57,6 +57,9 @@ def removeWxPrefixes(node):
def removeWxPrefix(name):
"""
Remove the "wx" prefix from a name, except for those which should keep it.
"""
if name.startswith('wx.') or name.startswith('``wx.'):
return name
@@ -70,7 +73,6 @@ def removeWxPrefix(name):
class FixWxPrefix(object):
"""
A mixin class that can help with removing the wx prefix, or changing it
@@ -568,7 +570,11 @@ def runGenerators(module):
# Toss in the PI generator too
from etgtools import pi_generator
generators.append(pi_generator.PiWrapperGenerator())
# Now the item map generator
from etgtools import map_generator
generators.append((map_generator.ItemMapGenerator()))
# And finally add the documentation generator
generators.append(getDocsGenerator())

98
sphinxtools/constants.py
View File

@@ -85,107 +85,11 @@ MODULENAME_REPLACE = {'_core' : 'wx.',
'_msw' : 'wx.msw.',
}
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.',
'GenericCalendarCtrl' : 'wx.adv.',
'OwnerDrawnComboBox' : 'wx.adv.',
# Enums/constants
'AnimationType' : 'wx.adv.',
'CalendarDateBorder' : 'wx.adv.',
'CalendarHitTestResult' : 'wx.adv.',
'LayoutAlignment' : 'wx.adv.',
'LayoutOrientation' : 'wx.adv.',
'OwnerDrawnComboBoxPaintingFlags': 'wx.adv.',
'SashDragStatus' : 'wx.adv.',
'SashEdgePosition' : 'wx.adv.',
'TaskBarIconType' : 'wx.adv.',
'TipKind' : 'wx.adv.',
# -- wxDataView -- #
# Widgets
'DataViewItemObjectMapper': 'wx.dataview.',
'PyDataViewModel' : 'wx.dataview.',
# Enums/constants
'DataViewCellMode' : 'wx.dataview.',
'DataViewCellRenderState' : 'wx.dataview.',
'DataViewColumnFlags' : 'wx.dataview.',
# -- wxHTML -- #
# Widgets
'HTMLHelpDialog' : 'wx.html.',
'HTMLHelpFrame' : 'wx.html.',
'HTMLHelpWindow' : 'wx.html.',
# Enums/constants
'HTMLCursor' : 'wx.html.',
'HtmlOpeningStatus' : 'wx.html.',
'HtmlScriptMode' : 'wx.html.',
'HtmlSelectionState' : 'wx.html.',
'HtmlURLType' : 'wx.html.',
# -- wxHTML2 -- #
# Widgets
# Enums/constants
'WebViewBackend' : 'wx.html2.',
'WebViewNavigationError' : 'wx.html2.',
'WebViewReloadFlags' : 'wx.html2.',
'WebViewZoom' : 'wx.html2.',
'WebViewZoomType' : 'wx.html2.',
# -- wxXML -- #
# Widgets
# Enums/constants
'XmlDocumentLoadFlag' : 'wx.xml.',
'XmlNodeType' : 'wx.xml.',
# -- wxXRC -- #
# Widgets
'XmlSubclassFactory' : 'wx.xrc.',
# Enums/constants
'XmlResourceFlags' : 'wx.xrc.',
# -- wx.msw -- #
'PyAxBaseWindow' : 'wx.msw',
}
# Other C++ specific things to strip away
CPP_ITEMS = ['*', '&', 'const', 'unsigned', '(size_t)', 'size_t', 'void']
# Serie of paths containing the input data for Sphinx and for the scripts
# Series of paths containing the input data for Sphinx and for the scripts
# building the ReST docs:
# The location of the Phoenix main folder

2
sphinxtools/postprocess.py
View File

@@ -334,7 +334,7 @@ def removeUnreferenced(input, class_summary, enum_base, unreferenced_classes, te
if split not in unreferenced_classes[reg]:
unreferenced_classes[reg].append(split)
text = text.replace(':ref:`%s`'%reg, '`%s`'%reg, 1)
text = text.replace(':ref:`%s`'%reg, '`%s` '%reg, 1)
return text, unreferenced_classes

79
sphinxtools/utilities.py
View File

@@ -14,8 +14,6 @@ import sys
import os
import codecs
import shutil
import glob
import imp
import re
if sys.version_info < (3,):
@@ -28,12 +26,10 @@ else:
string_base = str
# Phoenix-specific imports
from buildtools.config import phoenixDir
from .templates import TEMPLATE_CONTRIB
from .constants import IGNORE, PUNCTUATION, MODULENAME_REPLACE
from .constants import CPP_ITEMS, VERSION, VALUE_MAP, NO_MODULE
from .constants import CPP_ITEMS, VERSION, VALUE_MAP
from .constants import RE_KEEP_SPACES, EXTERN_INHERITANCE
from .constants import DOXYROOT, SPHINXROOT, WIDGETS_IMAGES_ROOT
@@ -104,30 +100,6 @@ class ODict(UserDict):
return list(map(self.get, self._keys))
# ----------------------------------------------------------------------- #
def removeWxPrefix(name):
"""
Removes the `wx` prefix from a string.
:param string `name`: a string, possibly starting with "wx" or "``wx".
:rtype: `string`
.. note:: This function is similar to the one already present in `tweaker_tools`
but I had to extend it a bit to suite the ReSTification of the XML docs.
"""
if name.startswith('wx') and not name.startswith('wxEVT_') and not name.startswith('wx.'):
name = name[2:]
if name.startswith('``wx') and not name.startswith('``wxEVT_') and not name.startswith('``wx.'):
name = name[0:2] + name[4:]
return name
# ----------------------------------------------------------------------- #
def isNumeric(input_string):
@@ -246,6 +218,7 @@ def pythonizeType(ptype, is_param):
:rtype: `string`
"""
from etgtools.tweaker_tools import removeWxPrefix
if 'size_t' in ptype:
ptype = 'int'
@@ -330,6 +303,7 @@ def convertToPython(text):
:rtype: `string`
"""
from etgtools.tweaker_tools import removeWxPrefix
newlines = []
unwanted = ['Include file', '#include']
@@ -452,13 +426,14 @@ def findControlImages(elementOrString):
exists for others, the missing images will be replaced by the "no_appearance.png"
file (you can find it inside the ``WIDGETS_IMAGES_ROOT`` folder.
"""
"""
from etgtools.tweaker_tools import removeWxPrefix
if isinstance(elementOrString, string_base):
class_name = py_class_name = elementOrString.lower()
else:
element = elementOrString
class_name = removeWxPrefix(element.name) or element.pyName
class_name = element.pyName if element.pyName else removeWxPrefix(element.name)
py_class_name = wx2Sphinx(class_name)[1]
class_name = class_name.lower()
@@ -694,50 +669,19 @@ 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.
ALL_ITEMS = {}
def class2Module():
global ALL_ITEMS
if ALL_ITEMS:
return ALL_ITEMS
etg_files = glob.glob(os.path.join(phoenixDir(), 'etg') + '/*.py')
etg_files = [files for files in etg_files if not files.startswith('_')]
for files in etg_files:
split = os.path.split(os.path.splitext(files)[0])[1]
module = imp.load_source(split, files)
current_module = MODULENAME_REPLACE.get(module.MODULE, '')
for item in module.ITEMS:
item = removeWxPrefix(item)
ALL_ITEMS[item] = current_module
ALL_ITEMS.update(NO_MODULE)
return ALL_ITEMS
def wx2Sphinx(name):
"""
Converts a wxWidgets specific string into a Phoenix-ReST-ready string.
:param string `name`: any string.
"""
from etgtools.tweaker_tools import removeWxPrefix
if '<' in name:
name = name[0:name.index('<')]
name = name.strip()
name = name.strip()
newname = fullname = removeWxPrefix(name)
if '.' in newname and len(newname) > 3:
@@ -747,9 +691,10 @@ def wx2Sphinx(name):
lookup = newname
remainder = ''
all_items = class2Module()
if lookup in all_items:
fullname = all_items[lookup] + lookup + remainder
from etgtools.item_module_map import ItemModuleMap
imm = ItemModuleMap()
if lookup in imm:
fullname = imm[lookup] + lookup + remainder
return newname, fullname