Lerking/Phoenix
1
0
Fork 0
mirror of https://github.com/wxWidgets/Phoenix.git synced 2025-07-21 12:41:10 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity
Files
e2f853d0e0e60567891cc1627448c36e35710141
Phoenix/sphinxtools/constants.py
Robin Dunn e2f853d0e0 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.
2016-05-19 21:04:14 -07:00

373 lines
15 KiB
Python
Raw Blame History

# -*- coding: utf-8 -*-
#---------------------------------------------------------------------------
# Name: sphinxtools/constants.py
# Author: Andrea Gavana
#
# Created: 30-Nov-2010
# Copyright: (c) 2013 by Total Control Software
# License: wxWindows License
#---------------------------------------------------------------------------
# Standard library imports
import os
import re
import datetime
# Phoenix-specific imports
import buildtools.version as version
from buildtools.config import phoenixDir, wxDir
# List of strings that should be ignored when creating inline literals
# such as ``ID_ANY`` or ``HORIZONTAL``, with double backticks
IGNORE = ['wxPython', 'wxWidgets', 'wxOSX', 'wxMGL', 'wxDFB', 'wxMAC', 'wxGTK', 'wxGTK2', 'wxUniversal',
'OS', 'X', 'OSX', 'DFB', 'MAC', 'GTK', 'GTK2', 'MSW', 'wxMSW', 'X11', 'OS2', 'MS', 'XP', 'GTK+',
'UI', 'GUI', '--', 'OTOH', 'GDI+', 'API', 'NT', 'RTL', 'GDI', '3D', 'MDI', 'SDI', 'TDI', 'URL',
'XPM', 'HTML', 'MIME', 'C++', 'XDG', 'A4', 'A5', 'KDE', 'GNOME', 'XFCE', 'CSS', 'IE', 'FONT',
'SIZE', 'COLOR', 'NOT', 'DOES']
# C++ stuff to Python/ReST stuff
VALUE_MAP = {'true': '``True``',
'false': '``False``',
'``NULL``': '``None``',
'NULL': '``None``',
'L{OSX}': '`OSX`',
'ctor': 'constructor',
}
# This is a list of instances in Phoenix (i.e., without documentation strings), and
# For the sake of beauty of the docs they get the inline literal treatment (double backticks)
CONSTANT_INSTANCES = ['NullAcceleratorTable', 'TheApp', 'DefaultPosition', 'DefaultSize',
'DefaultCoord', 'Coord', 'TheBrushList', 'TheColourDatabase',
'NullFont', 'NullBrush', 'NullPalette', 'NullPen', 'EmptyString',
'TheFontList', 'NullIcon', 'NullBitmap', 'constructor', 'ThePenList',
'DefaultValidator', 'String.Capitalize']
# Phoenix full version
VERSION = '%d.%d.%d' % (version.VER_MAJOR, version.VER_MINOR, version.VER_RELEASE)
# Things to chop away when ReST-ifying the docstrings
PUNCTUATION = '!"#$%\'()*,./:;<=>?@\\^{|}~'
# Conversion between XML sections and ReST sections
SECTIONS = [('return' , ':returns:'),
('since' , '.. versionadded::'),
('deprecated', '.. deprecated::'),
('warning' , '.. warning::'),
('remarks' , '.. note::'),
('remark' , '.. note::'),
('available' , '.. availability::'),
('note' , '.. note::'),
('see' , '.. seealso::'),
('todo' , '.. todo::'),
('par' , '')]
# List of things to remove/ignore (there may be more)
REMOVED_LINKS = ['Library:', 'Category:', 'Predefined objects/pointers:']
# Dictionary mapping the etg module name to the real Phoenix module name
# This needs to be kept up to date when other stuff comes in (i.e., wx.grid,
# wx.html and so on)
MODULENAME_REPLACE = {'_core' : 'wx.',
'_dataview': 'wx.dataview.',
'_adv' : 'wx.adv.',
'_stc' : 'wx.stc.',
'_html' : 'wx.html.',
'_html2' : 'wx.html2.',
'_glcanvas': 'wx.glcanvas.',
'_xml' : 'wx.xml.',
'_xrc' : 'wx.xrc.',
'_grid' : 'wx.grid.',
'_richtext': 'wx.richtext.',
'_webkit' : 'wx.webkit.',
'_media' : 'wx.media.',
'_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
# building the ReST docs:
# The location of the Phoenix main folder
PHOENIXROOT = phoenixDir()
# The location of the Sphinx main folder
SPHINXROOT = os.path.join(PHOENIXROOT, 'docs', 'sphinx')
# Where the snippets found in the XML docstrings live (There are C++, unconverted and
# converted Python snippets in 3 sub-folders
SNIPPETROOT = os.path.join(SPHINXROOT, 'rest_substitutions', 'snippets')
# A folder where some of the difficult-to-translate-to-ReST tables are. There are 4 of
# them up to now, for various reasons:
# 1. The wx.Sizer flags table is a grid table, very difficult to ReSTify automatically
# 2. The wx.ColourDatabase table of colour comes up all messy when ReSTified from XML
# 3. The "wxWidgets 2.8 Compatibility Functions" table for wx.VScrolledWindow
# 4. The wx.ArtProvider table
TABLEROOT = os.path.join(SPHINXROOT, 'rest_substitutions', 'tables')
# Folder where to save the inheritance diagrams for the classes
INHERITANCEROOT = os.path.join(SPHINXROOT, '_static', 'images', 'inheritance')
# Folder where to save the images found in the wxWidgets overviews or in the XML
# docstrings
OVERVIEW_IMAGES_ROOT = os.path.join(SPHINXROOT, '_static', 'images', 'overviews')
# Folder where to save the widgets screenshots (full-size, no thumbnails here)
WIDGETS_IMAGES_ROOT = os.path.join(SPHINXROOT, '_static', 'images', 'widgets', 'fullsize')
# Folder for the icons used for titles, sub-titles and so on for the Sphinx documentation
SPHINX_IMAGES_ROOT = os.path.join(SPHINXROOT, '_static', 'images', 'sphinxdocs')
DOCSTRING_KEY = '__module_docstring'
# The Doxygen root for the XML docstrings
xmlsrcbase = 'docs/doxygen/out/xml'
WXWIN = wxDir()
XMLSRC = os.path.join(WXWIN, xmlsrcbase)
DOXYROOT = os.path.join(WXWIN, 'docs', 'doxygen')
# Dictionary copied over from tweaker_tools
MAGIC_METHODS = {
'operator!=' : '__ne__',
'operator==' : '__eq__',
'operator+' : '__add__',
'operator-' : '__sub__',
'operator*' : '__mul__',
'operator/' : '__div__',
'operator+=' : '__iadd__',
'operator-=' : '__isub__',
'operator*=' : '__imul__',
'operator/=' : '__idiv__',
'operator bool' : '__int__', # Why not __nonzero__?
# TODO: add more
}
SECTIONS_EXCLUDE = {
'ConfigBase' : ('Related Include Files', '|phoenix_title| Example'),
'KeyboardState': ('This class is implemented ', '.. seealso::'),
'Menu' : ('|phoenix_title| Allocation strategy', '|phoenix_title| Event handling'),
'MouseState' : ('This class is implemented', '.. seealso::'),
'Panel' : ('Please see :ref:`/', 'if not all characters'),
'TextCtrl' : ('|phoenix_title| TextCtrl and C++ Streams', '|phoenix_title| Event Handling'),
'TextEntry' : ('Notice that you need', 'Currently this method is only '),
}
# A regex to split a string keeping the whitespaces
RE_KEEP_SPACES = re.compile(r'(\s+)')
# A list of things used in the post-processing of the HTML files generated by Sphinx
# This list is used only to insert a HTML horizontal line (<hr>) after each method/function
# description
HTML_REPLACE = ['module', 'function', 'method', 'class', 'classmethod', 'staticmethod', 'attribute']
# Today's date representation for the Sphinx HTML docs
TODAY = datetime.date.today().strftime('%d %B %Y')
# Inheritance diagram external hyperlinks
PYTHON_DOCS = 'http://docs.python.org/library/'
NUMPY_DOCS = 'http://docs.scipy.org/doc/numpy/reference/generated/'
EXTERN_INHERITANCE = {'UserDict.' : PYTHON_DOCS,
'ctypes.' : PYTHON_DOCS,
'code.' : PYTHON_DOCS,
'exceptions.': PYTHON_DOCS,
'threading.' : PYTHON_DOCS,
'numpy.' : NUMPY_DOCS
}
# wx.lib and other pure-Python stuff
class Enumeration(object):
def __init__(self, name, enumList):
self.__doc__ = name
lookup = { }
reverseLookup = { }
i = 0
uniqueNames = [ ]
uniqueValues = [ ]
for item in enumList:
x = item.upper()
uniqueNames.append(x)
uniqueValues.append(i)
lookup[x] = i
reverseLookup[i] = x
i = i + 1
self.lookup = lookup
self.reverseLookup = reverseLookup
def __getattr__(self, attr):
if not attr in self.lookup:
raise AttributeError
return self.lookup[attr]
def whatis(self, value):
return self.reverseLookup[value]
CONSTANT_RE = re.compile('^([\w\s,]+)=', re.M)
EXCLUDED_ATTRS = ['__builtins__', '__doc__', '__name__', '__file__', '__path__',
'__module__', '__all__']
TYPE_DESCRIPTION = ['library',
'package',
'py_module', 'pyd_module', 'pyc_module', 'pyw_module',
'klass',
'function',
'method', 'static_method', 'class_method', 'instance_method',
'method_descriptor', 'builtin_method', 'builtin_function',
'property',
'booltype', 'classtype', 'complextype', 'dictproxytype', 'dicttype', 'filetype',
'floattype', 'instancetype', 'inttype', 'lambdatype', 'listtype', 'longtype',
'nonetype', 'objecttype', 'slicetype', 'strtype', 'tracebacktype', 'tupletype',
'typetype', 'unicodetype', 'unknowntype', 'xrangetype']
object_types = Enumeration('Object_Types', TYPE_DESCRIPTION)
MODULE_TO_ICON = [(".py", object_types.PY_MODULE, "Py_Module"), (".pyd", object_types.PYD_MODULE, "Pyd_Module"),
(".pyc", object_types.PYC_MODULE, "Pyc_Module"), (".pyw", object_types.PYW_MODULE, "Pyw_Module"),
(".so", object_types.PYD_MODULE, "Pyd_Module")]
# wx.tools and other stuff
DOXY_2_REST = [('@author:', '\n.. moduleauthor:: '),
('@deprecated:', '\n.. deprecated:: '),
('@param', ':param'),
('@var', ':param'),
('@keyword', ':keyword'),
('@kwarg', ':keyword'),
('@note:', '\n.. note:: '),
('@package:', '\n**Package:** '),
('@package', '\n**Package:** '),
('@postcondition:', '\n:postcondition: '),
('@pre:', '\n:precondition: '),
('@precondition:', '\n:precondition: '),
('@requires:', '\n:requires: '),
('@returns:', '\n:returns: '),
('@return:', '\n:returns: '),
('@returns', '\n:returns: '),
('@return', '\n:returns: '),
('@rtype:', '\n:rtype: '),
# ('@section', XXX), Deal with this separately
('@see:', '\n.. seealso:: '),
('@status:', '\n.. todo:: '),
('@summary:', '\n**Summary:** '),
('@throws:', '\n:raise: '),
('@todo:', '\n.. todo:: '),
('@verbatim ', ''), # TODO This one
('@verbatim', ''), # TODO This one
('@endverbatim ', ''), # TODO This one
('@endverbatim', ''), # TODO This one
('@version:', '\n:version: ')]
Reference in New Issue View Git Blame Copy Permalink