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

Phoenix: Add support for documenting wx.lib, wx.py and wx.tools (that's the whole wxPython/Phoenix documentation)

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@71139 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Andrea Gavana
2012-04-07 21:00:39 +00:00
parent 67f0a02945
commit ff175387b3
24 changed files with 1105 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
build.py
View File

@@ -68,8 +68,9 @@ Usage: ./build.py [command(s)] [options]
SIP files SIP files
sphinx Run the documentation building process using Sphinx (this sphinx Run the documentation building process using Sphinx (this
needs to be done after dox and etg) needs to be done after dox and etg)
wxlib Run the documentation building process using Sphinx for wxlib Run the documentation building process using Sphinx for wx.lib
wx.lib (and possibly other pure-Python modules/packages) wxpy Run the documentation building process using Sphinx for wx.py
wxtools Run the documentation building process using Sphinx for wx.tools
sip Run sip sip Run sip
test Run the unit test suite test Run the unit test suite
test_* Run just one test module test_* Run just one test module
@@ -125,7 +126,7 @@ def main(args):
elif cmd in ['dox', 'doxhtml', 'etg', 'sip', 'touch', 'test', elif cmd in ['dox', 'doxhtml', 'etg', 'sip', 'touch', 'test',
'build_wx', 'build_py', 'setup_py', 'waf_py', 'build', 'bdist', 'build_wx', 'build_py', 'setup_py', 'waf_py', 'build', 'bdist',
'clean', 'clean_wx', 'clean_py', 'cleanall', 'clean_sphinx', 'clean', 'clean_wx', 'clean_py', 'cleanall', 'clean_sphinx',
'sphinx', 'wxlib']: 'sphinx', 'wxlib', 'wxpy', 'wxtools']:
function = globals()[cmd] function = globals()[cmd]
function(options, args) function(options, args)
else: else:
@@ -598,7 +599,7 @@ def sphinx(options, args):
def wxlib(options, args): def wxlib(options, args):
from sphinxtools.modulehunter import ModuleHunter from sphinxtools.modulehunter import ModuleHunter
cmdTimer = CommandTimer('wxlib') cmdTimer = CommandTimer('wx.lib')
pwd = pushDir(phoenixDir()) pwd = pushDir(phoenixDir())
libDir = os.path.join(phoenixDir(), 'wx', 'lib') libDir = os.path.join(phoenixDir(), 'wx', 'lib')
@@ -613,6 +614,42 @@ def wxlib(options, args):
ModuleHunter(init_name, import_name, version) ModuleHunter(init_name, import_name, version)
def wxpy(options, args):
from sphinxtools.modulehunter import ModuleHunter
cmdTimer = CommandTimer('wx.py')
pwd = pushDir(phoenixDir())
libDir = os.path.join(phoenixDir(), 'wx', 'py')
if not os.path.isdir(libDir):
raise Exception('Missing wx.py folder in the distribution')
init_name = os.path.join(libDir, '__init__.py')
import_name = 'py'
version = version3
ModuleHunter(init_name, import_name, version)
def wxtools(options, args):
from sphinxtools.modulehunter import ModuleHunter
cmdTimer = CommandTimer('wx.tools')
pwd = pushDir(phoenixDir())
libDir = os.path.join(phoenixDir(), 'wx', 'tools')
if not os.path.isdir(libDir):
raise Exception('Missing wx.tools folder in the distribution')
init_name = os.path.join(libDir, '__init__.py')
import_name = 'tools'
version = version3
ModuleHunter(init_name, import_name, version)
def sip(options, args): def sip(options, args):
cmdTimer = CommandTimer('sip') cmdTimer = CommandTimer('sip')
cfg = Config() cfg = Config()

15
docs/sphinx/_downloads/i18nwxapp/app_base.py
View File

@@ -26,6 +26,8 @@ def _displayHook(obj):
import __builtin__ import __builtin__
__builtin__.__dict__['_'] = wx.GetTranslation __builtin__.__dict__['_'] = wx.GetTranslation
import app_const as appC
from wx.lib.mixins.inspection import InspectionMixin from wx.lib.mixins.inspection import InspectionMixin
class BaseApp(wx.App, InspectionMixin): class BaseApp(wx.App, InspectionMixin):
@@ -35,13 +37,6 @@ class BaseApp(wx.App, InspectionMixin):
sys.displayhook = _displayHook sys.displayhook = _displayHook
self.appName = "I18N sample application" self.appName = "I18N sample application"
# define the translation domain, the name has to match your .mo files
self.langDomain = "I18Nwxapp"
# languages you want to support
self.supLang = {u"en": wx.LANGUAGE_ENGLISH,
u"fr": wx.LANGUAGE_FRENCH,
u"de": wx.LANGUAGE_GERMAN,
}
self.doConfig() self.doConfig()
@@ -89,8 +84,8 @@ class BaseApp(wx.App, InspectionMixin):
""" """
# if an unsupported language is requested default to English # if an unsupported language is requested default to English
if lang in self.supLang: if lang in appC.supLang:
selLang = self.supLang[lang] selLang = appC.supLang[lang]
else: else:
selLang = wx.LANGUAGE_ENGLISH selLang = wx.LANGUAGE_ENGLISH
@@ -101,7 +96,7 @@ class BaseApp(wx.App, InspectionMixin):
# create a locale object for this language # create a locale object for this language
self.locale = wx.Locale(selLang) self.locale = wx.Locale(selLang)
if self.locale.IsOk(): if self.locale.IsOk():
self.locale.AddCatalog(self.langDomain) self.locale.AddCatalog(appC.langDomain)
else: else:
self.locale = None self.locale = None

16
docs/sphinx/_downloads/i18nwxapp/app_const.py Normal file
View File

@@ -0,0 +1,16 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-#
#
# Author: Werner F. Bruhin
# Purpose: Application constants
# Created: 06/04/2012
import wx
# language domain
langDomain = "I18Nwxapp"
# languages you want to support
supLang = {u"en": wx.LANGUAGE_ENGLISH,
u"fr": wx.LANGUAGE_FRENCH,
u"de": wx.LANGUAGE_GERMAN,
}

28
docs/sphinx/_downloads/i18nwxapp/i18ntools/geni18n.py → docs/sphinx/_downloads/i18nwxapp/geni18n.py
View File

@@ -1,13 +1,14 @@
# -*- coding: utf-8 -*-# # -*- coding: utf-8 -*-#
#!/usr/bin/env python #!/usr/bin/env python
""" """
This will generate the .pot and .mo files for the application domain and languages defined below. This will generate the .pot and .mo files for the application domain and
languages defined below.
The .po and .mo files are placed as per convention in The .po and .mo files are placed as per convention in
"appfolder/locale/lang/LC_MESSAGES" "appfolder/locale/lang/LC_MESSAGES"
The .pot file is placed in the current folder. The .pot file is placed in the locale folder.
This script or something similar should be added to your build process. This script or something similar should be added to your build process.
@@ -18,16 +19,19 @@ catalog.
""" """
domainName = 'i18nwxapp' import app_const as appC
# define the languages you are supporting and need translation, so if texts
# in your source are English then you don't need 'en' here # we remove English as source code strings are in English
supLang = ['fr', 'de'] supportedLang = []
for l in appC.supLang:
if l != u"en":
supportedLang.append(l)
import os import os
import sys import sys
import subprocess import subprocess
appFolder, loc = os.path.split(os.getcwd()) appFolder = os.getcwd()
# setup some stuff to get at Python I18N tools/utilities # setup some stuff to get at Python I18N tools/utilities
@@ -37,12 +41,12 @@ pyToolsFolder = os.path.join(pyFolder, 'Tools')
pyI18nFolder = os.path.join(pyToolsFolder, 'i18n') pyI18nFolder = os.path.join(pyToolsFolder, 'i18n')
pyGettext = os.path.join(pyI18nFolder, 'pygettext.py') pyGettext = os.path.join(pyI18nFolder, 'pygettext.py')
pyMsgfmt = os.path.join(pyI18nFolder, 'msgfmt.py') pyMsgfmt = os.path.join(pyI18nFolder, 'msgfmt.py')
outFolder = os.getcwd() outFolder = os.path.join(appFolder, 'locale')
# build command for pygettext # build command for pygettext
gtOptions = '-a -d %s -o %s.pot -p %s %s' gtOptions = '-a -d %s -o %s.pot -p %s %s'
tCmd = pyExe + ' ' + pyGettext + ' ' + (gtOptions % (domainName, tCmd = pyExe + ' ' + pyGettext + ' ' + (gtOptions % (appC.langDomain,
domainName, appC.langDomain,
outFolder, outFolder,
appFolder)) appFolder))
print "Generating the .pot file" print "Generating the .pot file"
@@ -50,10 +54,10 @@ print "cmd: %s" % tCmd
rCode = subprocess.call(tCmd) rCode = subprocess.call(tCmd)
print "return code: %s\n\n" % rCode print "return code: %s\n\n" % rCode
for tLang in supLang: for tLang in supportedLang:
# build command for msgfmt # build command for msgfmt
langDir = os.path.join(appFolder, ('locale\%s\LC_MESSAGES' % tLang)) langDir = os.path.join(appFolder, ('locale\%s\LC_MESSAGES' % tLang))
poFile = os.path.join(langDir, domainName + '.po') poFile = os.path.join(langDir, appC.langDomain + '.po')
tCmd = pyExe + ' ' + pyMsgfmt + ' ' + poFile tCmd = pyExe + ' ' + pyMsgfmt + ' ' + poFile
print "Generating the .mo file" print "Generating the .mo file"

73
docs/sphinx/_downloads/i18nwxapp/i18ntools/i18nwxapp.pot
View File

@@ -1,73 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR ORGANIZATION
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2012-04-05 12:12+Paris, Madrid (heure d’été)\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n"
"Generated-By: pygettext.py 1.5\n"
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:17
msgid "The I18N sample application"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:28
msgid "Close"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:29
msgid "Close the application"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:31
msgid "&File"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:36
msgid "Edit something"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:37
msgid "Edit an entry of something"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:40
msgid "&Edit"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:45
msgid "&About"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:46
msgid "About the program"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:48
msgid "&Help"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:58
msgid "A nice label for the TextCtrl"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:62
msgid "a search control"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:68
msgid "Open a file dialog"
msgstr ""
#: h:\devProjectsT\PhoenixI18N\i18nwxapp\sampleapp.py:80
msgid "Choose a file"
msgstr ""

BIN
docs/sphinx/_downloads/i18nwxapp/i18nwxapp.zip
View File

Binary file not shown.

73
docs/sphinx/_downloads/i18nwxapp/locale/I18Nwxapp.pot Normal file
View File

@@ -0,0 +1,73 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR ORGANIZATION
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2012-04-07 10:49+Paris, Madrid (heure d’été)\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n"
"Generated-By: pygettext.py 1.5\n"
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:17
msgid "The I18N sample application"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:28
msgid "Close"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:29
msgid "Close the application"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:31
msgid "&File"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:36
msgid "Edit something"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:37
msgid "Edit an entry of something"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:40
msgid "&Edit"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:45
msgid "&About"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:46
msgid "About the program"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:48
msgid "&Help"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:58
msgid "A nice label for the TextCtrl"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:63
msgid "a search control"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:70
msgid "Open a file dialog"
msgstr ""
#: h:\devProjectsT\Phoenix\docs\sphinx\_downloads\i18nwxapp\sampleapp.py:82
msgid "Choose a file"
msgstr ""

BIN
docs/sphinx/_static/images/overviews/htmlcell_descent.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.9 KiB

BIN
docs/sphinx/_static/images/overviews/htmlcontcell_alignv.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

BIN
docs/sphinx/_static/images/overviews/htmlcontcell_indent.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/sphinx/_static/images/overviews/htmlwin_border.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.2 KiB

BIN
docs/sphinx/_static/images/overviews/overview_html_cont.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.4 KiB

BIN
docs/sphinx/_static/images/overviews/overview_html_contbox.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.5 KiB

BIN
docs/sphinx/_static/images/overviews/overview_html_hello.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

4
docs/sphinx/_templates/main.html
View File

@@ -94,6 +94,10 @@
</ul> </ul>
<p class="biglink"><a class="biglink" href="{{ pathto("lib") }}">wx.lib</a><br/> <p class="biglink"><a class="biglink" href="{{ pathto("lib") }}">wx.lib</a><br/>
<span class="linkdescr">Our pure-Python library of widgets</span></p> <span class="linkdescr">Our pure-Python library of widgets</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("py") }}">wx.py</a><br/>
<span class="linkdescr">The py package, formerly the PyCrust package.</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("tools") }}">wx.tools</a><br/>
<span class="linkdescr">Some useful tools and utilities for wxPython (Editra, XRCed).</span></p>
</td></tr> </td></tr>
</table> </table>

646
docs/sphinx/rest_substitutions/overviews/html_overview.rst Normal file
View File

@@ -0,0 +1,646 @@
.. include:: headings.inc
.. _html overview:
==================================
|phoenix_title| **HTML Overview**
==================================
The :mod:`html` library provides classes for parsing and displaying HTML.
It is not intended to be a high-end HTML browser. If you are looking for
something like that try http://www.mozilla.org/.
:mod:`html` can be used as a generic rich text viewer - for example to display a
nice About Box (like those of GNOME apps) or to display the result of
database searching. There is a :class:`FileSystem` class which allows you to use
your own virtual file systems.
:class:`~html.HtmlWindow` supports tag handlers. This means that you can easily extend
:mod:`html` library with new, unsupported tags. Not only that, you can even use
your own application-specific tags!
There is a generic :class:`~html.HtmlParser` class, independent of :class:`~html.HtmlWindow`.
.. _html quick start:
HTML quick start
----------------
Displaying HTML
~~~~~~~~~~~~~~~~
Class :class:`~html.HtmlWindow` (derived from :class:`ScrolledWindow`) is used to display
HTML documents.
It has two important methods: :meth:`~html.HtmlWindow.LoadPage` and
:meth:`~html.HtmlWindow.SetPage`. LoadPage loads and displays HTML file while SetPage
displays directly the passed **string**. See the example::
mywin.LoadPage("test.htm")
mywin.SetPage("htmlbody" \
"h1Error/h1" \
"Some error occurred :-H)" \
"/body/hmtl")
Setting up HtmlWindow
~~~~~~~~~~~~~~~~~~~~~~
Because :class:`~html.HtmlWindow` is derived from :class:`ScrolledWindow` and not from
:class:`Frame`, it doesn't have visible frame. But the user usually wants to see
the title of HTML page displayed somewhere and the frame's titlebar is the
ideal place for it.
:class:`~html.HtmlWindow` provides 2 methods in order to handle this:
:meth:`~html.HtmlWindow.SetRelatedFrame` and :meth:`~html.HtmlWindow.SetRelatedStatusBar`.
See the example::
html = wx.html.HtmlWindow(self)
html.SetRelatedFrame(self, "HTML : %%s")
html.SetRelatedStatusBar(0)
The first command associates the HTML object with its parent frame (this
points to :class:`Frame` object there) and sets the format of the title. Page
title "Hello, world!" will be displayed as "HTML : Hello, world!" in this
example.
The second command sets which frame's status bar should be used to display
browser's messages (such as "Loading..." or "Done" or hypertext links).
Customizing HtmlWindow
~~~~~~~~~~~~~~~~~~~~~~~
You can customize :class:`~html.HtmlWindow` by setting font size, font face and borders
(space between border of window and displayed HTML). Related functions:
- :meth:`~html.HtmlWindow.SetFonts`
- :meth:`~html.HtmlWindow.SetBorders`
- :meth:`~html.HtmlWindow.ReadCustomization`
- :meth:`~html.HtmlWindow.WriteCustomization`
The last two functions are used to store user customization info :class:`Config`
stuff (for example in the registry under Windows, or in a dotfile under
Unix).
HTML Printing
--------------
The :mod:`html` library provides printing facilities with several levels of
complexity. The easiest way to print an HTML document is to use the
:class:`~html.HtmlEasyPrinting` class.
It lets you print HTML documents with only one command and you don't have to
worry about deriving from the :class:`Printout` class at all. It is only a simple
wrapper around the :class:`~html.HtmlPrintout`, normal wxPython printout class.
And finally there is the low level class :class:`~html.HtmlDCRenderer` which you can
use to render HTML into a rectangular area on any DC.
It supports rendering into multiple rectangles with the same width. (The most
common use of this is placing one rectangle on each page or printing into two
columns.)
.. _help files format:
Help Files Format
------------------
:mod:`html` library can be used to show an help manual to the user; in fact, it
supports natively (through :class:`~html.HtmlHelpController`) a reduced version of MS
HTML Workshop format.
A **book** consists of three files: the header file, the contents file and
the index file.
You can make a regular zip archive of these files, plus the HTML and any
image files, for HTML (or helpview) to read; and the ``".zip"`` file can
optionally be renamed to ``".htb"``.
Header file (.hhp)
~~~~~~~~~~~~~~~~~~~
.. highlight:: rst
The header file must contain these lines (and may contain additional lines
which are ignored)::
Contents file=filename.hhc
Index file=filename.hhk
Title=title of your book
Default topic=default page to be displayed.htm
All filenames (including the Default topic) are relative to the location of
the ``".hhp"`` file.
.. note::
For localization, in addition the ``".hhp"`` file may contain the line::
Charset=rfc_charset
which specifies what charset (e.g. "iso8859_1") was used in contents and
index files. Please note that this line is incompatible with MS HTML Help
Workshop and it would either silently remove it or complain with some error.
Contents file (.hhc)
~~~~~~~~~~~~~~~~~~~~~
.. highlight:: html
Contents file has HTML syntax and it can be parsed by regular HTML parser. It
contains exactly one list (``<ul>`` ... ``</ul>`` statement)::
<ul>
<li><object type="text/sitemap">
<param name="Name" value="@topic name@">
<param name="ID" value=@numeric_id@>
<param name="Local" value="@filename.htm@">
</object></li>
<li><object type="text/sitemap">
<param name="Name" value="@topic name@">
<param name="ID" value=@numeric_id@>
<param name="Local" value="@filename.htm@">
</object></li>
</ul>
You can modify value attributes of param tags. The *topic name* is name of
chapter/topic as is displayed in contents, *filename.htm* is the HTML page
name (relative to the ``".hhp"`` file) and *numeric_id* is optional - it is
used only when you use :meth:`~html.HtmlHelpController.Display`.
Items in the list may be nested - one ``<li>`` statement may contain a
``<ul>`` sub-statement::
<ul>
<li><object type="text/sitemap">
<param name="Name" value="Top node">
<param name="Local" value="top.htm">
</object></li>
<ul>
<li><object type="text/sitemap">
<param name="Name" value="subnode in
topnode">
<param name="Local" value="subnode1.htm">
</object></li>
</ul>
<li><object type="text/sitemap">
<param name="Name" value="Another Top">
<param name="Local" value="top2.htm">
</object></li>
</ul>
Index file (.hhk)
~~~~~~~~~~~~~~~~~~
Index files have same format as contents files except that ID params are
ignored and sublists are **not** allowed.
Input Filters
--------------
The :mod:`html` library provides a mechanism for reading and displaying files of
many different file formats.
:meth:`~html.HtmlWindow.LoadPage` can load not only HTML files but any known file. To
make a file type known to :class:`~html.HtmlWindow` you must create a :class:`~html.HtmlFilter`
filter and register it using :meth:`~html.HtmlWindow.AddFilter`.
Cells and Containers
---------------------
This article describes mechanism used by :class:`~html.HtmlWinParser` and
:class:`~html.HtmlWindow` to parse and display HTML documents.
Cells
~~~~~~
You can divide any text (or HTML) into small fragments. Let's call these
fragments **cells**. Cell is for example one word, horizontal line, image or
any other part of document. Each cell has width and height (except special
"magic" cells with zero dimensions - e.g. colour changers or font changers).
See :class:`~html.HtmlCell`.
Containers
~~~~~~~~~~~
Container is kind of cell that may contain sub-cells. Its size depends on
number and sizes of its sub-cells (and also depends on width of window). See
:class:`~html.HtmlContainerCell`, :meth:`~html.HtmlCell.Layout`. This image shows the cells and
containers:
.. image:: _static/images/overviews/overview_html_contbox.png
:alt: overview_html_contbox.png
Using Containers in Tag Handler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:class:`~html.HtmlWinParser` provides a user-friendly way of managing containers. It is
based on the idea of opening and closing containers.
Use :meth:`~html.HtmlWinParser.OpenContainer` to open new a container *within* an
already opened container. This new container is a *sub-container* of the old
one. (If you want to create a new container with the same depth level you can
call ``CloseContainer()``; ``OpenContainer()``; ).
Use :meth:`~html.HtmlWinParser.CloseContainer` to close the container. This doesn't
create a new container with same depth level but it returns "control" to the
parent container. See explanation:
.. image:: _static/images/overviews/overview_html_cont.png
:alt: overview_html_cont.png
There clearly must be same number of calls to OpenContainer as to CloseContainer.
Example
::::::::
.. highlight:: python
This code creates a new paragraph (container at same depth level) with "Hello, world!"::
myParser.CloseContainer()
c = myParser.OpenContainer()
myParser.AddText("Hello, ")
myParser.AddText("world!")
myParser.CloseContainer()
myParser.OpenContainer()
and here is image of the situation:
.. image:: _static/images/overviews/overview_html_hello.png
:alt: overview_html_hello.png
You can see that there was an opened container before the code was executed.
We closed it, created our own container, then closed our container and opened
new container.
The result was that we had *same* depth level after executing. This is
general rule that should be followed by tag handlers: leave depth level of
containers unmodified (in other words, number of OpenContainer and
CloseContainer calls should be same within :meth:`~html.HtmlTagHandler.HandleTag` 's
body).
.. note::
Notice that it would be usually better to use
:meth:`~html.HtmlContainerCell.InsertCell` instead of adding text to the parser
directly.
Tag Handlers
-------------
The :mod:`html` library provides architecture of pluggable *tag* handlers. Tag
handler is class that understands particular HTML tag (or tags) and is able
to interpret it.
:class:`~html.HtmlWinParser` has a static table of **modules**. Each module contains
one or more tag handlers. Each time a new :class:`~html.HtmlWinParser` object is
constructed all modules are scanned and handlers are added to HtmlParser's
list of available handlers.
How it works
~~~~~~~~~~~~~
Common tag handler's :meth:`~html.HtmlTagHandler.HandleTag` method works in four
steps:
- Save state of parent parser into local variables
- Change parser state according to tag's params
- Parse text between the tag and paired ending tag (if present)
- Restore original parser state
See :class:`~html.HtmlWinParser` for methods for modifying parser's state. In general
you can do things like opening/closing containers, changing colors, fonts etc...
Providing own tag handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the :mod:`lib.wxpTag` on how to provide your own tag handlers.
Tag handlers
~~~~~~~~~~~~~
The handler is derived from :class:`~html.HtmlWinTagHandler` (or directly from
:class:`~html.HtmlTagHandler`).
Tags supported by :mod:`html`
-----------------------------
:mod:`html` is not a full implementation of HTML standard. Instead, it supports most
common tags so that it is possible to display *simple* HTML documents with
it. (For example it works fine with pages created in Netscape Composer or
generated by tex2rtf).
Following tables list all tags known to :mod:`html`, together with supported
parameters.
A tag has general form of ``tagname`` param_1 param_2 ... param_n where
param_i is either ``paramname="paramvalue"`` or ``paramname=paramvalue`` -
these two are equivalent. Unless stated otherwise, :mod:`html` is case-
insensitive.
Table of common parameter values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We will use these substitutions in tags descriptions:
+------------------+---------------------------------------------------------------+
| [alignment] | CENTER |
| +---------------------------------------------------------------+
| | LEFT |
| +---------------------------------------------------------------+
| | RIGHT |
| +---------------------------------------------------------------+
| | JUSTIFY |
+------------------+---------------------------------------------------------------+
| [v_alignment] | TOP |
| +---------------------------------------------------------------+
| | BOTTOM |
| +---------------------------------------------------------------+
| | CENTER |
+------------------+---------------------------------------------------------------+
| [color] | HTML 4.0-compliant colour specification |
+------------------+---------------------------------------------------------------+
| [fontsize] | -2 |
| +---------------------------------------------------------------+
| | -1 |
| +---------------------------------------------------------------+
| | +0 |
| +---------------------------------------------------------------+
| | +1 |
| +---------------------------------------------------------------+
| | +2 |
| +---------------------------------------------------------------+
| | +3 |
| +---------------------------------------------------------------+
| | +4 |
| +---------------------------------------------------------------+
| | 1 |
| +---------------------------------------------------------------+
| | 2 |
| +---------------------------------------------------------------+
| | 3 |
| +---------------------------------------------------------------+
| | 4 |
| +---------------------------------------------------------------+
| | 5 |
| +---------------------------------------------------------------+
| | 6 |
| +---------------------------------------------------------------+
| | 7 |
+------------------+---------------------------------------------------------------+
| [pixels] | integer value that represents dimension in pixels |
+------------------+---------------------------------------------------------------+
| [percent] | i% |
| +---------------------------------------------------------------+
| | where i is integer |
+------------------+---------------------------------------------------------------+
| [url] | an URL |
+------------------+---------------------------------------------------------------+
| [string] | text string |
+------------------+---------------------------------------------------------------+
| [coords] | c(1),c(2),c(3),...,c(n) |
| +---------------------------------------------------------------+
| | where c(i) is integer |
+------------------+---------------------------------------------------------------+
List of supported tags
~~~~~~~~~~~~~~~~~~~~~~~
+------------------+---------------------------------------------------------------+
| A | NAME=[string] |
| +---------------------------------------------------------------+
| | HREF=[url] |
| +---------------------------------------------------------------+
| | TARGET=[target window spec] |
+------------------+---------------------------------------------------------------+
| ADDRESS | |
+------------------+---------------------------------------------------------------+
| AREA | SHAPE=POLY |
| +---------------------------------------------------------------+
| | SHAPE=CIRCLE |
| +---------------------------------------------------------------+
| | SHAPE=RECT |
| +---------------------------------------------------------------+
| | COORDS=[coords] |
| +---------------------------------------------------------------+
| | HREF=[url] |
+------------------+---------------------------------------------------------------+
| BIG | |
+------------------+---------------------------------------------------------------+
| BLOCKQUOTE | |
+------------------+---------------------------------------------------------------+
| BODY | TEXT=[color] |
| +---------------------------------------------------------------+
| | LINK=[color] |
| +---------------------------------------------------------------+
| | BGCOLOR=[color] |
+------------------+---------------------------------------------------------------+
| BR | ALIGN=[alignment] |
+------------------+---------------------------------------------------------------+
| CENTER | |
+------------------+---------------------------------------------------------------+
| CITE | |
+------------------+---------------------------------------------------------------+
| CODE | |
+------------------+---------------------------------------------------------------+
| DD | |
+------------------+---------------------------------------------------------------+
| DIV | ALIGN=[alignment] |
+------------------+---------------------------------------------------------------+
| DL | |
+------------------+---------------------------------------------------------------+
| DT | |
+------------------+---------------------------------------------------------------+
| EM | |
+------------------+---------------------------------------------------------------+
| FONT | COLOR=[color] |
| +---------------------------------------------------------------+
| | SIZE=[fontsize] |
| +---------------------------------------------------------------+
| | FACE=[comma-separated list of facenames] |
+------------------+---------------------------------------------------------------+
| HR | ALIGN=[alignment] |
| +---------------------------------------------------------------+
| | SIZE=[pixels] |
| +---------------------------------------------------------------+
| | WIDTH=[percent|pixels] |
| +---------------------------------------------------------------+
| | NOSHADE |
+------------------+---------------------------------------------------------------+
| H1 | |
+------------------+---------------------------------------------------------------+
| H2 | |
+------------------+---------------------------------------------------------------+
| H3 | |
+------------------+---------------------------------------------------------------+
| H4 | |
+------------------+---------------------------------------------------------------+
| H5 | |
+------------------+---------------------------------------------------------------+
| H6 | |
+------------------+---------------------------------------------------------------+
| I | |
+------------------+---------------------------------------------------------------+
| IMG | SRC=[url] |
| +---------------------------------------------------------------+
| | WIDTH=[percent|pixels] |
| +---------------------------------------------------------------+
| | HEIGHT=[pixels] |
| +---------------------------------------------------------------+
| | ALIGN=TEXTTOP |
| +---------------------------------------------------------------+
| | ALIGN=CENTER |
| +---------------------------------------------------------------+
| | ALIGN=ABSCENTER |
| +---------------------------------------------------------------+
| | ALIGN=BOTTOM |
| +---------------------------------------------------------------+
| | USEMAP=[url] |
+------------------+---------------------------------------------------------------+
| KBD | |
+------------------+---------------------------------------------------------------+
| LI | |
+------------------+---------------------------------------------------------------+
| MAP | NAME=[string] |
+------------------+---------------------------------------------------------------+
| META | HTTP-EQUIV="Content-Type" |
| +---------------------------------------------------------------+
| | CONTENT=[string] |
+------------------+---------------------------------------------------------------+
| OL | |
+------------------+---------------------------------------------------------------+
| P | ALIGN=[alignment] |
+------------------+---------------------------------------------------------------+
| PRE | |
+------------------+---------------------------------------------------------------+
| SAMP | |
+------------------+---------------------------------------------------------------+
| SMALL | |
+------------------+---------------------------------------------------------------+
| SPAN | |
+------------------+---------------------------------------------------------------+
| STRIKE | |
+------------------+---------------------------------------------------------------+
| STRONG | |
+------------------+---------------------------------------------------------------+
| SUB | |
+------------------+---------------------------------------------------------------+
| SUP | |
+------------------+---------------------------------------------------------------+
| TABLE | ALIGN=[alignment] |
| +---------------------------------------------------------------+
| | WIDTH=[percent|pixels] |
| +---------------------------------------------------------------+
| | BORDER=[pixels] |
| +---------------------------------------------------------------+
| | VALIGN=[v_alignment] |
| +---------------------------------------------------------------+
| | BGCOLOR=[color] |
| +---------------------------------------------------------------+
| | CELLSPACING=[pixels] |
| +---------------------------------------------------------------+
| | CELLPADDING=[pixels] |
+------------------+---------------------------------------------------------------+
| TD | ALIGN=[alignment] |
| +---------------------------------------------------------------+
| | VALIGN=[v_alignment] |
| +---------------------------------------------------------------+
| | BGCOLOR=[color] |
| +---------------------------------------------------------------+
| | WIDTH=[percent|pixels] |
| +---------------------------------------------------------------+
| | COLSPAN=[pixels] |
| +---------------------------------------------------------------+
| | ROWSPAN=[pixels] |
| +---------------------------------------------------------------+
| | NOWRAP |
+------------------+---------------------------------------------------------------+
| TH | ALIGN=[alignment] |
| +---------------------------------------------------------------+
| | VALIGN=[v_alignment] |
| +---------------------------------------------------------------+
| | BGCOLOR=[color] |
| +---------------------------------------------------------------+
| | WIDTH=[percent|pixels] |
| +---------------------------------------------------------------+
| | COLSPAN=[pixels] |
| +---------------------------------------------------------------+
| | ROWSPAN=[pixels] |
+------------------+---------------------------------------------------------------+
| TITLE | |
+------------------+---------------------------------------------------------------+
| TR | ALIGN=[alignment] |
| +---------------------------------------------------------------+
| | VALIGN=[v_alignment] |
| +---------------------------------------------------------------+
| | BGCOLOR=[color] |
+------------------+---------------------------------------------------------------+
| TT | |
+------------------+---------------------------------------------------------------+
| U | |
+------------------+---------------------------------------------------------------+
| UL | |
+------------------+---------------------------------------------------------------+
List of supported styles
~~~~~~~~~~~~~~~~~~~~~~~~~
:mod:`html` doesn't really have CSS support but it does support a few simple
styles: you can use ``"text-align"``, ``"width"``, ``"vertical-align"`` and
``"background"`` with all elements and for ``SPAN`` elements a few other
styles are additionally recognized:
- ``color``
- ``font-family``
- ``font-size`` (only in point units)
- ``font-style`` (only "oblique", "italic" and "normal" values are supported)
- ``font-weight`` (only "bold" and "normal" values are supported)
- ``text-decoration`` (only "underline" value is supported)

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

@@ -152,6 +152,7 @@ The new wxPython API documentation is available `in this page <main.html>`_.
filesystem_overview filesystem_overview
font_encodings font_encodings
font_overview font_overview
html_overview
internationalization internationalization
listctrl_overview listctrl_overview
log_classes_overview log_classes_overview
@@ -171,6 +172,8 @@ The new wxPython API documentation is available `in this page <main.html>`_.
window_styles_overview window_styles_overview
dataview.1classindex dataview.1classindex
lib lib
py
tools
Indices and tables Indices and tables

60
docs/sphinx/rest_substitutions/overviews/internationalization.rst
View File

@@ -11,7 +11,7 @@
|phoenix_title| **Internationalization Overview** |phoenix_title| **Internationalization Overview**
================================================== ==================================================
"Internationalization" (often referred to as I18N) is the process to change an "Internationalization" (often referred to as i18n) is the process to change an
application so that all user visible texts are translated to the user selected application so that all user visible texts are translated to the user selected
language and that things like dates, money amounts and numbers in general are language and that things like dates, money amounts and numbers in general are
shown in a format the user is familiar with/or used to. shown in a format the user is familiar with/or used to.
@@ -25,24 +25,27 @@ Text translation
Prepare the source code Prepare the source code
----------------------- -----------------------
Text translation in Python is done using gettext [1]_ , to ensure that all wxPython Text translation in Python is done using gettext [1]_ , to ensure that all
labels are also translated we will use :class:`Locale` and :func:`GetTranslation` . wxPython labels are also translated we will use :class:`Locale` and
:func:`GetTranslation` .
How to prepare your source code to enable translation of texts:: How to prepare your source code to enable translation of texts::
aString = _(u"This is a string which will be translated") aString = _(u"This is a string which will be translated")
As you can see it is very simple, you just enclose the text with the translation function "_()", As you can see it is very simple, you just enclose the text with the translation
obviously there is a bit more to it, see below. function "_()", obviously there is a bit more to it, see below.
Enabling I18N for a whole application you would do some setup in the application file along the following lines: Enabling I18N for a whole application you would do some setup in the application
file along the following lines:
.. literalinclude:: _downloads/i18nwxapp/app_base.py .. literalinclude:: _downloads/i18nwxapp/app_base.py
:lines: 25-27 :lines: 25-27
Here we setup the "_" translation function and making it available application by adding it to builtin. Here we setup the "_" translation function and making it available application
by adding it to builtin.
The code required to change to a different language is as follows: The code required to change to a different language is as follows:
@@ -53,39 +56,44 @@ The code required to change to a different language is as follows:
Do the actual translation work Do the actual translation work
------------------------------ ------------------------------
You need to extract all the text strings marked by the "_" function, a little script `geni18n.py` is in the You need to extract all the text strings marked by the "_" function, a little
:download:`downloadable zip file <_downloads/i18nwxapp/i18nwxapp.zip>`, it will extract all the strings script `geni18n.py` is in the :download:`downloadable zip file <_downloads/i18nwxapp/i18nwxapp.zip>`,
and generate a ``.pot`` file. The `geni18n.py` script will also generate the ``.mo`` files for defined languages. it will extract all the strings and generate a ``.pot`` file, which is put to
the locale folder. The `geni18n.py` script will also generate the ``.mo`` files
for defined languages.
The ``.pot`` file is then provided to the translators and they use it to generate a ``.po`` file for The ``.pot`` file is then provided to the translators and they use it to
the language they translate too or they can also use the ``.pot`` file to merge new/changed text strings generate a ``.po`` file for the language they translate too or they can also use
to an existing ``.po`` file. the ``.pot`` file to merge new/changed text strings to an existing ``.po`` file.
To do the actual translation we recomment `poEdit` [2]_ , it allows you to create or update a translation To do the actual translation we recomment `poEdit` [2]_ , it allows you to
catalog (``.po`` file) from the ``.pot`` file. create or update a translation catalog (``.po`` file) from the ``.pot`` file.
Sample application Sample application
------------------ ------------------
In the :download:`downloadable zip file <_downloads/i18nwxapp/i18nwxapp.zip>` we included a small In the :download:`downloadable zip file <_downloads/i18nwxapp/i18nwxapp.zip>`
sample application showing the above in action. we included a small sample application showing the above in action.
- `app_base.py` contains the initialization code - `app_base.py` contains the initialization code
- `sampleapp.py` is the main frame/application, just run this to see things in action - `sampleapp.py` is the main frame/application, just run this to see things in action
- `i18ntools/geni18n.py` is the script to generate the ``.pot`` file and it also generates the ``.mo`` files. - `geni18n.py` is the script to generate the ``.pot`` file and it also generates the ``.mo`` files.
.. note:: .. note::
The application has a button which displays a file dialog, as wxPython uses a native widget for this the The application has a button which displays a file dialog, as wxPython uses
text are shown in the operating system language and not the language which is selected in `app_base.py`. a native widget for this the text are shown in the operating system language
and not the language which is selected in `app_base.py`.
Localization overview Localization overview
===================== =====================
"Localization", often referred to as "L10N", is the process to adapt the display of dates and numbers to local custom. "Localization", often referred to as "L10n", is the process to adapt the display
of dates and numbers to local custom.
E.g. "4/5/2012" would for an American mean April 5. 2012, but for most Europeans it would be 4. May 2012. E.g. "4/5/2012" would for an American mean April 5. 2012, but for most Europeans
it would be 4. May 2012.
Localize dates Localize dates
@@ -100,6 +108,14 @@ Localize numbers
.. todo:: to be written .. todo:: to be written
Additional resources
====================
- http://zetcode.com/wxpython/in18/
- http://wiki.wxpython.org/Internationalization
- http://en.wikipedia.org/wiki/Internationalization_and_localization
.. rubric:: Footnotes .. rubric:: Footnotes
.. [1] gettext - http://docs.python.org/library/gettext.html .. [1] gettext - http://docs.python.org/library/gettext.html

2
docs/sphinx/rest_substitutions/snippets/python/converted/ContextHelp.1.py Normal file
View File

@@ -0,0 +1,2 @@
contextHelp = wx.ContextHelp(myWindow)

4
docs/sphinx/rest_substitutions/snippets/python/converted/HelpControllerBase.SetViewer.1.py Normal file
View File

@@ -0,0 +1,4 @@
self.help.SetViewer("kdehelp")
self.help.SetViewer("gnome-help-browser")
self.help.SetViewer("netscape", wx.HELP_NETSCAPE)

4
etgtools/sphinx_generator.py
View File

@@ -1673,7 +1673,9 @@ class Emphasis(Node):
tail = child.element.tail tail = child.element.tail
tail = (tail is not None and [tail] or [''])[0] tail = (tail is not None and [tail] or [''])[0]
childText = childText.replace(ConvertToPython(tail), '') if tail.strip() != ':':
childText = childText.replace(ConvertToPython(tail), '')
fullChildText = child.Join() fullChildText = child.Join()
endPos = text.index(childText) endPos = text.index(childText)

32
sphinxtools/constants.py
View File

@@ -209,3 +209,35 @@ MODULE_TO_ICON = [(".py", object_types.PY_MODULE, "Py_Module"), (".pyd", obje
(".pyc", object_types.PYC_MODULE, "Pyc_Module"), (".pyw", object_types.PYW_MODULE, "Pyw_Module"), (".pyc", object_types.PYC_MODULE, "Pyc_Module"), (".pyw", object_types.PYW_MODULE, "Pyw_Module"),
(".so", object_types.PYD_MODULE, "Pyd_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: ')]

225
sphinxtools/librarydescription.py
View File

@@ -11,12 +11,14 @@ from inspect import getmro, getclasstree, getdoc, getcomments
from utilities import MakeSummary, ChopDescription, WriteSphinxOutput from utilities import MakeSummary, ChopDescription, WriteSphinxOutput
from utilities import FindControlImages, PickleClassInfo from utilities import FindControlImages, PickleClassInfo
from constants import object_types, MODULE_TO_ICON from constants import object_types, MODULE_TO_ICON, DOXY_2_REST
import templates import templates
ENOENT = getattr(errno, 'ENOENT', 0) ENOENT = getattr(errno, 'ENOENT', 0)
EPIPE = getattr(errno, 'EPIPE', 0) EPIPE = getattr(errno, 'EPIPE', 0)
EPYDOC_PATTERN = re.compile(r'\S+{\S+}', re.DOTALL)
reload(sys) reload(sys)
sys.setdefaultencoding("utf-8") sys.setdefaultencoding("utf-8")
@@ -73,7 +75,7 @@ def generic_summary(libraryItem, stream):
table = [] table = []
for item in sub_list: for item in sub_list:
if item.is_redundant or item.GetShortName().startswith('__test'): if item.is_redundant or item.GetShortName().startswith('__test') or '.extern.' in item.name:
continue continue
docs = ChopDescription(ReplaceWxDot(item.docs)) docs = ChopDescription(ReplaceWxDot(item.docs))
@@ -106,7 +108,154 @@ def ReplaceWxDot(text):
# Masked is funny... # Masked is funny...
text = text.replace('</LI>', '') text = text.replace('</LI>', '')
return text
space_added = False
for old, new in DOXY_2_REST:
if old not in text:
continue
if new in [':keyword', ':param']:
if not space_added:
space_added = True
new_with_newline = '\n%s'%new
text = text.replace(old, new_with_newline, 1)
text = text.replace(old, new)
lines = text.splitlines(True)
newtext = ''
for line in lines:
if '@section' not in line:
newtext += line
continue
# Extract the section header
splitted = line.split()
header = ' '.join(line[2:])
header = header.strip()
newtext += header + '\n'
newtext += '-'*len(header) + '\n\n'
return newtext
def GetTopLevelParent(klass):
parent = klass.parent
if not parent:
return klass
parents = [parent]
while parent:
parent = parent.parent
parents.append(parent)
return parents[-2]
def FindInHierarchy(klass, newlink):
library = GetTopLevelParent(klass)
return library.FindItem(newlink)
def FindBestLink(klass, newlink):
parent_class = klass.parent
if klass.kind in range(object_types.FUNCTION, object_types.INSTANCE_METHOD):
if parent_class.GetShortName() == newlink:
return ':class:`%s`'%newlink
else:
child_names = [sub.GetShortName() for sub in parent_class.children]
if newlink in child_names:
index = child_names.index(newlink)
child = parent_class.children[index]
if child.kind in range(object_types.PACKAGE, object_types.PYW_MODULE+1):
return ':mod:`~%s`'%child.name
elif child.kind in range(object_types.FUNCTION, object_types.INSTANCE_METHOD):
return ':meth:`~%s`'%child.name
else:
return ':class:`~%s`'%child.name
full_loop = FindInHierarchy(klass, newlink)
if full_loop:
return full_loop
return ':ref:`%s`'%newlink
def KillEpydoc(klass, newtext):
epydocs = re.findall(EPYDOC_PATTERN, newtext)
if not epydocs:
return newtext
newepydocs = epydocs[:]
for item in epydocs:
if '#{' in item:
# this is for masked stuff
newepydocs.remove(item)
if not newepydocs:
return newtext
for regex in newepydocs:
start = regex.index('{')
end = regex.index('}')
if 'U{' in regex:
# Simple link, leave it as it is
newlink = regex[start+1:end]
elif 'C{' in regex:
# It's an inclined text, but we can attach some
# class reference to it
newlink = regex[start+1:end]
if 'wx.' in regex or 'wx' in regex:
newlink = newlink.replace('wx.', '')
newlink = newlink.replace('wx', '')
newlink = ':class:`%s`'%newlink.strip()
else:
newlink = '`%s`'%newlink
elif 'I{' in regex:
# It's an inclined text
newlink = regex[start+1:end]
newlink = ' `%s` '%newlink
elif 'L{' in regex:
# Some kind of link, but we can't figure it out
# very easily from here... just use :ref:
newlink = regex[start+1:end]
if newlink.upper() == newlink:
# Use double backticks
newlink = '``%s``'%newlink
else:
# Try and reference it
bestlink = FindBestLink(klass, newlink)
if bestlink:
newlink = bestlink
else:
# Something else, don't bother for the moment
continue
newtext = newtext.replace(regex, newlink)
return newtext
class ParentBase(object): class ParentBase(object):
@@ -275,6 +424,42 @@ class Library(ParentBase):
self.Walk(child) self.Walk(child)
def FindItem(self, newlink, obj=None):
if obj is None:
obj = self
# must have at least root folder
children = obj.GetChildren()
bestlink = ''
if not children:
return bestlink
# check each name
for child in children:
if child.is_redundant:
continue
parts = child.name.split('.')
dotname = '.'.join(parts[-2:])
if child.name.endswith(newlink) and (child.GetShortName() == newlink or dotname == newlink):
if child.kind in range(object_types.PACKAGE, object_types.PYW_MODULE+1):
return ':mod:`~%s`'%child.name
elif child.kind in range(object_types.FUNCTION, object_types.INSTANCE_METHOD+1):
return ':meth:`~%s`'%child.name
else:
return ':class:`~%s`'%child.name
bestlink = self.FindItem(newlink, child)
if bestlink:
return bestlink
return bestlink
def GetPythonVersion(self): def GetPythonVersion(self):
return self.python_version return self.python_version
@@ -288,7 +473,10 @@ class Library(ParentBase):
header = templates.TEMPLATE_DESCRIPTION%(self.base_name, self.base_name) header = templates.TEMPLATE_DESCRIPTION%(self.base_name, self.base_name)
stream.write(header) stream.write(header)
stream.write(ReplaceWxDot(self.docs) + '\n\n') newtext = ReplaceWxDot(self.docs)
stream.write(newtext + '\n\n')
newtext = KillEpydoc(self, newtext)
generic_summary(self, stream) generic_summary(self, stream)
WriteSphinxOutput(stream, self.sphinx_file) WriteSphinxOutput(stream, self.sphinx_file)
@@ -320,7 +508,7 @@ class Module(ParentBase):
def ToRest(self): def ToRest(self):
if self.is_redundant or self.GetShortName().startswith('__test'): if self.is_redundant or self.GetShortName().startswith('__test') or '.extern.' in self.name:
return return
stream = StringIO() stream = StringIO()
@@ -336,7 +524,11 @@ class Module(ParentBase):
header = templates.TEMPLATE_DESCRIPTION%(self.name, '%s'%self.GetShortName()) header = templates.TEMPLATE_DESCRIPTION%(self.name, '%s'%self.GetShortName())
stream.write(header) stream.write(header)
stream.write(ReplaceWxDot(self.docs) + '\n\n')
newtext = ReplaceWxDot(self.docs)
stream.write(newtext + '\n\n')
newtext = KillEpydoc(self, newtext)
spacer = ' '*self.name.count('.') spacer = ' '*self.name.count('.')
@@ -443,7 +635,7 @@ class Class(ParentBase):
def ToRest(self): def ToRest(self):
if self.is_redundant or self.GetShortName().startswith('__test'): if self.is_redundant or self.GetShortName().startswith('__test') or '.extern.' in self.name:
return return
stream = StringIO() stream = StringIO()
@@ -455,6 +647,7 @@ class Class(ParentBase):
stream.write('.. highlight:: python\n\n') stream.write('.. highlight:: python\n\n')
class_docs = ReplaceWxDot(self.docs) class_docs = ReplaceWxDot(self.docs)
class_docs = KillEpydoc(self, class_docs)
header = templates.TEMPLATE_DESCRIPTION%(self.name, self.GetShortName()) header = templates.TEMPLATE_DESCRIPTION%(self.name, self.GetShortName())
stream.write(header) stream.write(header)
@@ -536,7 +729,10 @@ class Class(ParentBase):
index = self.signature.index(' def __init__') index = self.signature.index(' def __init__')
self.signature = self.signature[0:index] self.signature = self.signature[0:index]
self.signature.strip() self.signature = self.signature.strip()
if len(self.signature) < 2:
self.is_redundant = True
class ChildrenBase(object): class ChildrenBase(object):
@@ -642,6 +838,9 @@ class Method(ChildrenBase):
index = self.signature.index(' def ') index = self.signature.index(' def ')
self.signature = self.signature[index+5:].strip() self.signature = self.signature[index+5:].strip()
if '*' in self.signature:
self.signature = self.signature.replace('*', r'\*')
if not self.signature.strip(): if not self.signature.strip():
self.is_redundant = True self.is_redundant = True
@@ -668,14 +867,16 @@ class Method(ChildrenBase):
return return
text = '' text = ''
for line in self.docs.splitlines(): newdocs = ReplaceWxDot(self.docs)
text += indent + ReplaceWxDot(line) + '\n'
text += '\n\n' for line in newdocs.splitlines(True):
text += indent + line
text = KillEpydoc(self, text)
text += '\n\n\n'
stream.write(text) stream.write(text)
class Property(ChildrenBase): class Property(ChildrenBase):
def __init__(self, name, item): def __init__(self, name, item):

8
sphinxtools/modulehunter.py
View File

@@ -509,7 +509,7 @@ def SubImport(import_string, module, parent_class, ispkg):
submod = __import__(import_string, fromlist=[module]) submod = __import__(import_string, fromlist=[module])
except: except:
# pubsub and Editra can be funny sometimes... # pubsub and Editra can be funny sometimes...
message = "Unable to import module/package '%s'.\n Exception was: %s"%(module, format_traceback()) message = "Unable to import module/package '%s.%s'.\n Exception was: %s"%(import_string, module, format_traceback())
print "\nWARNING: %s\n"%message print "\nWARNING: %s\n"%message
return None, 0 return None, 0
@@ -518,6 +518,10 @@ def SubImport(import_string, module, parent_class, ispkg):
filename = getfile(submod) filename = getfile(submod)
subpath = os.path.dirname(filename)
if subpath not in sys.path:
sys.path.append(subpath)
if ispkg: if ispkg:
kind = object_types.PACKAGE kind = object_types.PACKAGE
else: else:
@@ -545,7 +549,7 @@ def SubImport(import_string, module, parent_class, ispkg):
def ModuleHunter(init_name, import_name, version): def ModuleHunter(init_name, import_name, version):
pickle_file = os.path.join(os.getcwd(), 'docs', 'sphinx', 'wxlib.pkl') pickle_file = os.path.join(os.getcwd(), 'docs', 'sphinx', 'wx%s.pkl'%import_name)
if os.path.isfile(pickle_file): if os.path.isfile(pickle_file):
fid = open(pickle_file, 'rb') fid = open(pickle_file, 'rb')