---------------
Project Phoenix
---------------

See http://wiki.wxpython.org/ProjectPhoenix for information and goals
about this project.


Directory structure
-------------------

There are a lot of subfolders in this directory, here is a brief
explanation to help a newbie find their way around.

 * build            Intermediate files produced by the build process
                    (distutils, etc.) are stored here.  This folder 
                    should not be committed to a version repository.

 * buildtools  	    This is a Python package containing modules that
                    are used from setup.py and which assist with
                    configuring and running the build.

 * etg              This is where the Extractor-Tweaker-Generator
                    scripts are stored (see the ProjectPhoenix link
                    above.)  These scripts are invoked by the build
                    and they will read the XML files produced by
                    Doxygen and will produce interface definition
                    files for SIP (or perhaps for other backend
                    generators in the future.)

 * etgtools         This Python package contains modules which assist
                    with the parsing of the XML files, tweaking the
                    collection of objects produced by the parser, and
                    also the backend generation of code or
                    documentation.

 * sip/gen          The code (.sip and .py files) produced by the ETG
                    scripts is placed in this folder.

 * sip/cpp          The code produced when running SIP is put in this
                    folder.  It will be C++ source and header files,
                    and also some extra files with information about
                    the source files produced so the build knows what
                    files to compile.

 * sip/siplib       This is a copy of the SIP runtime library.  We
                    have our own copy so it can be included with the
                    wxPython build as an extension module with a
                    unique name (wx.siplib) and to not require a
                    runtime dependency on SIP being installed on the
                    target system.  3rd party extensions that want to
                    integrate with wxPython should ensure that the
                    sip.h they #include is the one in this folder.

 * src              This folder is for any other source code (SIP, C++,
                    Python, or anything else) that is edited by hand
                    instead of being generated by some tool.

 * wx               This is the top of the wxPython package.  For an
                    in-place buld the extension modules and any
                    associated files will be put into this folder.
                    Subfolders contain pure-python subpackages of the
                    wx package, such as wx.lib, etc.


Naming of files
---------------

To help keep things a little easier when looking for things that need to be
worked on, the file names in the Phoenix project will mirror the names of the
files in the wxWidgets interface headers folder. For example, if there is a
interface/wx/FOO.h and we are processing the XML produced for that file then
the ETG script for the classes and other items will be named etg/FOO.py and it
will produce sip/gen/FOO.sip, unit tests will be in unittests/test_FOO.py, and
and so on.

In most cases more than one ETG/SIP file will be used to create a single
Python extension module. In those cases there will be one ETG script used to
bring all the others together into the single extension module (by using the
back-end generator's include feature for example.) The names of those scripts
will have a leading underscore, such as etg/_core.py, and all the scripts that
are intended to be included in that extension module should specify that name
in their MODULE variable.