Clarify submodule usage a bit more.

Add the Prerequisites section to the top level README.
Tweak and prettify.

README.rst

@@ -3,7 +3,8 @@ wxPython Project Phoenix
 =========================
 
 .. image:: demo/bitmaps/splash.png
-
+   :align: center
+   
 Welcome to wxPython's Project Phoenix! This project is a new implementation
 of wxPython focused on improving speed, maintainability and extensibility.
 Just like "Classic" wxPython it wraps the wxWidgets C++ toolkit and provides
@@ -21,6 +22,8 @@ project and information about how you can help out.
 How to build Phoenix
 --------------------
 
+First of all, review the section below about prerequisites.  
+
 All aspects of the Phoenix build are managed through a series of commands
 provided by the build.py script. There is also a setup.py script available
 for those who are used to the standard distutils or setuptools types of
@@ -111,7 +114,8 @@ process.
 * **build**: Build both wxWidgets and wxPython. There are additional
   commands if you want to build just one or the other. The results will be
   put in the Phoenix/wx folder, and can be used from there without
-  installation if desired.
+  installation if desired, by setting PYTHONPATH so the Phoenix/wx package 
+  dir is found by Python.
 
 Some other useful commands and options are:
 
@@ -178,6 +182,18 @@ explanation to help a newbie find their way around.
   parsing of the XML files, tweaking the collection of objects produced by
   the parser, and also the backend generation of code or documentation.
 
+ * **ext**: This folder holds the source for external projects used by
+   Phoenix, (currently just wxWidgets) as git submodules. This allows Phoenix
+   to use a specific revision of the code in the other projects and not depend
+   on the developer fetching the correct version of the code on their own.
+
+   When you first checkout the Phoenix source using git you will need to tell
+   git to also fetch the submodules, like this:
+
+      cd Phoenix
+      git submodule init
+      git submodule update
+
 * **sip/gen**: The code (.sip files) produced by the ETG scripts is placed
   in this folder.
 
@@ -227,5 +243,76 @@ in their MODULE variable.
 Prerequisites
 --------------
 
-TBW
+The following are some tips about what is required to build Phoenix for
+yourself. There are likely some other things that may not have been mentioned
+here, if you find something else that should be mentioned then please submit
+a PR for updating this document.
+
+**Windows**
+
+    All the source code needed for wxWidgets and wxPython Phoenix are
+    included in the wxWidgets and Phoenix source trees. In addition to a
+    stock Python installation you will also need a copy of Visual Studio 2008
+    (for Python2.7 compatibility) or Visual Studio 2010 (for Python 3.x
+    support). It should also be possible to build using Mingw32, but there
+    will need to be some changes made to the build scripts to support that.
+    
+    You may also want to get a copy of the MS SDK in order to have newer
+    definitions of the Windows API. I typically use 7.0 or 7.1 with Visual
+    Studio 2008.
+
+    Unfortunately Microsoft no longer distributes Visual Studio 2008. But
+    don't panic! They have recently made available a "Microsoft Visual C++
+    Compiler for Python 2.7" package. I haven't tried it but I expect it will
+    work fine for building Phoenix. Plus it's free! You can get it at:
+    http://www.microsoft.com/en-us/download/details.aspx?id=44266
+
+    If you want to build Phoenix with debug info then you will need to first
+    build a debug version of Python, and then use that Python (python_d.exe) to
+    build Phoenix.
+    
+**Linux**
+
+    On Ubuntu the following development packages and their dependencies
+    should be installed in order to build Phoenix. Other debian-like distros
+    will probably also have these or similarly named packages available.
+    Extrapolate accordingly for other linux distributions or other unixes.
+
+        * dpkg-dev 
+        * build-essential 
+        * python2.7-dev     # use appropriate Python version
+        * libwebkitgtk-dev
+        * libjpeg-dev 
+        * libtiff-dev
+        * libgtk2.0-dev
+        * libsdl1.2-dev 
+        * libgstreamer-plugins-base0.10-dev
+        * freeglut3 
+        * freeglut3-dev
+
+**Mac OSX**
+
+    Like the Windows platform all the source and libs you need for building
+    Phoenix on OSX are included in the wxWidgets and Phoenix source trees, or
+    by default on the system. In addition you will need to get the Xcode
+    compiler and SDKs, if you don't already have it, from
+    https://developer.apple.com/ (free registration required). You should
+    also install the command line tools for your version of Xcode and OSX.
+    This can usually be done from within Xcode or via a separate installer
+    package.
+
+    Also like on Windows, using the same or similar compiler that was used to
+    build Python usually helps things to work better and have a better chance
+    for success. For example, the stock Python 2.7 will try to use "gcc-4.2"
+    when building extensions, but newer versions of Xcode may not have that
+    command available. I am currently using Xcode 4.6.3, and I have symlinks
+    in ``/usr/local/bin`` pointing to the ``/usr/bin/llvm-*-4.2`` executables.
+    
+    If all else fails it is not too hard to build Python yourself using
+    whatever Xcode you have installed, and then use that Python when buildign
+    Phoenix.
+
+
+.. image:: docs/phoenix-fire-md.png
+   :width: 100%
 

ext/README.txt

@@ -9,6 +9,7 @@ fetching the correct version of the code on their own.
 When you first checkout the Phoenix source using git you will need to tell git
 to also fetch the submodules, like this:
 
+    cd Phoenix
     git submodule init
     git submodule update
 
@@ -22,12 +23,14 @@ To learn more about git submodules, please see the following:
 Notes to self
 =============
 
- * To clone repos with submodules:
+ * To clone repositories with submodules:
 
        git clone <repourl>
+       cd <repo>
        git submodule init
+       git submodule update
 
- * To update a submodule from its upstream:
+ * To update an existing submodule from its upstream:
 
        git submodule update --remote <submodule>