New documentation directory.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@20357 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

wxPython/docs/PyManual.txt

@@ -0,0 +1,76 @@
+===============
+ The Py Manual
+===============
+
+-------------------------
+ Py - Served Fresh Daily 
+-------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Date: $Date$
+:Revision: $Revision$
+
+.. contents::
+
+
+Introduction
+============
+
+This document will show you how to make use of the Py programs and the
+py package of modules.
+
+
+What is Py?
+===========
+
+Py is really several things.  Py is a set of standalone programs as
+well as a library of modules that you can use in your own programs.
+
+First, Py contains standalone programs that provide code editors and
+graphical, Python shell interfaces.  Second, Py contains a collections
+of modules that you can use in your own wxPython applications to
+provide similar services, either for your own use during development,
+or as an interface for users of your program.  Third, Py containss a
+wrapper utility, providing you with runtime introspection capabilities
+for your wxPython programs without having to include PyCrust or
+PyShell in your program, or alter one line of your code.
+
+
+Py standalone programs
+======================
+
+There are several standalone applications in the Py package:
+
+* PyAlaCarte
+* PyAlaMode
+* PyCrust
+* PyFilling
+* PyShell
+* PyWrap
+
+
+Py modules
+==========
+
+Py was designed to be modular.  That means graphical code is kept
+separate from non-graphical code, and many of the Py modules can be
+used by other programs.  Likewise, other programs can supply some of
+the modules needed by Py.  For example, you could supply a customized
+interpreter module and plug it in to the PyCrust standalone
+application.  As long as it supports the minimum functionality
+required, PyCrust will work just as well with your interpreter as with
+its default interpreter.
+
+
+Py runtime wrapper
+==================
+
+The Py wrapper utility (``PyWrap.py``) lets you run an existing
+wxPython program with a PyCrust frame at the same time.  Inside the
+PyCrust shell, the local variable ``app`` is assigned to your
+application instance.  In this way you can introspect your entire
+application within the PyCrust shell and the PyFilling namespace
+viewer.  And through the use of the Py decorator classes, PyCrust can
+display wxPython function and method signatures as well as docstrings
+for the entire wxPython library.

wxPython/docs/default.css

@@ -0,0 +1,208 @@
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+
+.first {
+  margin-top: 0 }
+
+.last {
+  margin-bottom: 0 }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+dd {
+  margin-bottom: 0.5em }
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em }
+
+div.footer, div.header {
+  font-size: smaller }
+
+div.sidebar {
+  margin-left: 1em ;
+  border: medium outset ;
+  padding: 0em 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr {
+  width: 75% }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font-family: serif ;
+  font-size: 100% }
+
+pre.line-block {
+  font-family: serif ;
+  font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em ;
+  background-color: #eeeeee }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.option-argument {
+  font-style: italic }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+table {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.citation {
+  border-left: solid thin gray ;
+  padding-left: 0.5ex }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.footnote {
+  border-left: solid thin black ;
+  padding-left: 0.5ex }
+
+td, th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+th.docinfo-name, th.field-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+  font-size: 100% }
+
+tt {
+  background-color: #eeeeee }
+
+ul.auto-toc {
+  list-style-type: none }

wxPython/docs/docutils.conf

@@ -0,0 +1,6 @@
+[options]
+
+output_encoding: iso-8859-1
+source-link: 1
+datestamp: %Y-%m-%d %H:%M UTC
+generator: 1

wxPython/docs/wxPackage.txt

@@ -0,0 +1,144 @@
+=========================
+ The wxPython wx Package
+=========================
+
+--------------------------------------------------
+ Or, how to survive the new wx namespace changes.
+--------------------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Date: $Date$
+:Revision: $Revision$
+
+.. contents::
+
+
+.. Add a link to wxExamples.html
+
+
+
+Introduction
+============
+
+Big things sometimes come in small packages.  This is certainly true
+of the new wx package, which is being introduced as a transition to
+allow the "wx" prefix to be dropped from the names of all wxPython
+classes, functions, and constants.
+
+
+Why change anything?
+====================
+
+This change is being made for a couple of reasons.  The first reason
+is to discourage the use of ``import *``, which is a dangerous
+technique that can create name conflicts and bloated namespaces.
+
+The second reason is to remove what some perceive to be a "wart."  For
+example, the following code is rather ugly in that the "wx" prefix on
+the wxFrame class name is no longer useful when you're using the wx
+module prefix::
+
+    from wxPython import wx
+
+    class Frame(wx.wxFrame)
+
+The new wx package allows you to write code like this, instead::
+
+    import wx
+
+    class Frame(wx.Frame)
+
+The third reason is that the wxWindows project intends to do the same
+thing (implement a new wx namespace and drop the "wx" prefix) and we
+want wxPython to lead the way.
+
+
+What does the new wx package do?
+================================
+
+As a way of getting to this new syntax as quickly as possible, the
+code in this new wx package was created.  What it does is alter the
+existing wx namespace dynamically.  By making the changes on-the-fly
+at runtime, we can try out the new syntax before any permanent changes
+are made to the underlying class library.  The downside of making
+these changes at runtime is that there is a slight delay when you
+``import wx``; the upside is that you can start using the new syntax
+now.
+
+
+Will any of this effect my existing code?
+=========================================
+
+No.  Your existing code will continue to work and be supported for
+some time.  It will be up to you to decide when to switch to the new
+syntax.  But all new documentation and code examples will use the new
+syntax.  So don't wait too long.  You wouldn't want anyone calling you
+old-fashioned, would you?
+
+
+How does the new wx package work?
+=================================
+
+It's pretty simple, and pretty clever.  The wx directory contains an
+``__init__.py`` file, making it a Python package.  (In contrast, the
+old wxPython.wx module is a module, not a package.)  When you ``import
+wx`` the code in the ``__init__.py`` file is executed, and that's
+where all the magic takes place.  Let's take a look at the code inside
+the ``__init__.py`` file:
+
+.. include:: ../wx/__init__.py
+   :literal:
+
+Namespaces in Python are implemented as dictionaries.  The dictionary
+used to create the wx package's namespace is accessible using the
+``globals()`` function.  The dictionary used to create the old
+wxPython.wx module's namespace is ``wx.__dict__``.  Once we have these
+two dictionaries, it's a simple matter of iterating through one,
+changing the names, adding the renamed object to the other dictionary,
+and cleaning up a few local variables and imported modules.  Voila!
+
+
+What about all the other modules, like grid, html, and stc?
+===========================================================
+
+There's more to wxPython than just the wx namespace.  And we've got
+those extra modules covered as well.  For each of those modules (as
+well as the lib package) we've got matching modules in the new wx
+package.  Let's take a look at a few of them.
+
+Here is ``html.py``:
+
+.. include:: ../wx/html.py
+   :literal:
+
+And here is ``lib/dialogs.py``:
+
+.. include:: ../wx/lib/dialogs.py
+   :literal:
+
+As you can see, they both rely on the ``prefix.rename()`` function
+defined in ``prefix.py``:
+
+.. include:: ../wx/prefix.py
+   :literal:
+
+Again, the technique is very similar to the one used by the wx
+package.
+
+
+How do I use it?
+================
+
+The wx package is created when you install wxPython.  So you can start
+using it now.  Examples are included in the wx/examples directory,
+which includes an examples.txt documentation file.  Here is the source
+code for ``hello.py``, a simple program that displays a wxPython
+graphic inside a frame:
+
+.. include:: ../samples/wx_examples/hello/hello.py
+   :literal:
+
+Good luck.  I hope you like the new wx package as much as I do.
+
+Pat

wxPython/docs/wxPythonExamples.txt

@@ -0,0 +1,99 @@
+=================================
+ Example Programs Using wxPython
+=================================
+
+--------------------------------------------------
+ A survival guide for the post-wx-prefixed world.
+--------------------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Date: $Date$
+:Revision: $Revision$
+
+.. contents::
+
+
+Introduction
+============
+
+If something hits you on the head, don't run around screaming that the
+sky is falling.  Instead, take a close look and see if it wasn't a
+"wx" prefix that hit you.  Apparently, they're dropping off wxPython
+class names like flies dropping dead in the scorching heat of a
+summer's day.
+
+Yes, the world is changing, and even our little wxPython world must
+change with it.  Then again, I'm not fond of pesky summertime flies,
+and I'm not too upset that the "wx" prefixes are going to bite the
+dust.  I think it's for the best.  But, being the kind, considerate
+person that I am, I decided to write this guide to make the wx
+namespace transition easier for everyone, even Chicken Little.
+
+.. sidebar:: Say what?
+
+   If you have no idea what I mean by the "wx namespace transition,"
+   consider yourself lucky.  You can simply use these examples to
+   learn wxPython in its current state.  All you need to know is that
+   previous wxPython code used a slightly different syntax that some
+   folks (including me) considered ugly.  So we changed it.  And
+   that's when the sky starting falling...
+
+Rather than simply **tell** you that everything will be okay, I
+decided to **show** you that everything will be okay.  To do that,
+I've created a bunch of example programs using the new wx package.  I
+hope you like them.
+
+
+Basic
+=====
+
+It doesn't get much simpler than this.  Every wxPython program needs
+an application and a frame.  To encourage good coding habits, I've
+split them into separate modules.  They don't do much, but they're a
+good starting point.
+
+I include a simple App class in the frame module because the PyCrust
+"wrapper" utility (``wrap.py``) only works with modules that contain
+an application class.  So including a simple one in each of your frame
+modules allows you to use the PyCrust runtime wrapper and debug your
+frames independent of your full application.
+
+Here is the module (``frame.py``) that defines the frame class:
+
+.. include:: ../samples/wx_examples/basic/frame.py
+   :literal:
+
+And here is the module (``app.py``) that defines the application class
+and imports the frame from ``frame.py``:
+
+.. include:: ../samples/wx_examples/basic/app.py
+   :literal:
+
+
+Hello
+=====
+
+This program displays an image file (``wxPython.jpg``) inside a frame
+sized to match the graphic.
+
+.. figure:: screenshots/hello-win98.png
+   :scale: 100
+
+   Running ``hello.py`` on Windows.
+
+.. figure:: screenshots/hello-linux.png
+   :scale: 100
+
+   Running ``hello.py`` on Linux.
+
+.. figure:: screenshots/hello-mac.png
+   :scale: 100
+
+   Running ``hello.py`` on Mac OS X.
+
+Here is the source code for ``hello.py``:
+
+.. include:: hello/hello.py
+   :literal:
+

wxPython/docs/wxPythonTutorial.txt

@@ -0,0 +1,39 @@
+=======================
+ The wxPython Tutorial
+=======================
+
+-----------------------------------------------------
+ How to get up and running with the wxPython toolkit
+-----------------------------------------------------
+
+:Author: Patrick K. O'Brien
+:Contact: pobrien@orbtech.com
+:Date: $Date$
+:Revision: $Revision$
+:License: wxWindows Free Documentation Licence, Version 3
+
+.. contents::
+
+
+Introduction
+============
+
+This is a tutorial for the wxPython GUI toolkit.
+
+
+What is wxPython?
+=================
+
+wxPython is a GUI toolkit for the Python programming language.  It
+allows Python programmers to create programs with a graphical user
+interface for Windows, Linux, and Mac OS X.
+
+
+License
+=======
+
+This document adheres to the same license as the other documentation
+that comes with wxWindows:
+
+.. include:: ../license/licendoc.txt
+   :literal: