Consider performing a
Phoenix Development Process
- This diagram represents the proposed development process and workflow for going from the wx interface files to the final wxPython bindings code and documentation.
- Shaded items are those that are created and maintained by hand, either transformation tools created by the developers or input files maintained by project developers.
- Other items are existing 3rd-party tools or the output files produced by the tools.
wx interface .h files
- These files already exist and are maintained by all of the wx developers and currently are primarily used for producing the wxWidgets documentation.
- They define the public C++ API of wxWidgets and although they are not an exact representation of the actual C++ code (some implementation-only or platform specific classes are skipped over in the hierarchy, etc.) they do represent the API intended to be used by the programmers and so make a good starting point for language bindings.
- It is assumed that the functions, classes and methods they do define are accurate and do match the corresponding C++ code well enough that a compile using the declared items would succeed.
- It is also assumed that as changes are made to the C++ code that the developer will make equivalent and correct changes to the interface files.
Extractors/Tweakers/Generators
- This box in the diagram represents a collection of scripts (let's call them ETG scripts) that do the work of converting the Doxygen XML files into what will be used to produce the wxPython extension modules and documentation.
- Each script does the extraction, tweaking and generating steps for the classes and functions in one or more of the XML files and will produce the code for one extension module.
- The final output of the ETG scripts is an input file for the chosen Bindings Generator with all the classes, methods, functions, etc. with annotations, extensions, augmentations needed for the Bindings Generator to create the extension modules for wxPython. A set of documentation files for those classes, functions, etc. will also be produced, which will be fed to the Docs Generator.
Extractors
- This stage of the process will parse the XML files and will create a collection of objects that represent the classes, methods, functions, etc. and contain the pertinent information for each that was gleaned from the XML.
- The extraction part of the ETG scripts will be fairly simple, probably just a few lines of code that feeds a set of XML files (or maybe just class names) to a builder library function that does all the work.
- There are also methods in the objects created by this step that enable easily finding objects within the collection and other things that can help out the tweaking part of the process.
Tweakers
- This is where we can change, augment or otherwise manipulate the objects produced by the extractor stage of the ETG scripts, in order to control how the generator produces the end result.
- Possible tweaks that can be done include things like:
- Changing the name of a class or method, or even things like parameter names.
- Setting a flag that will cause the generator to ignore a class or method.
- Removing or modifying what the generator will see for a function's parameters or parameter types.
- Specify that a function parameter is an output parameter used to return an extra value.
- Control which instances of an overloaded function are visible to the generator.
- Change whether a method is treated by the generator as virtual or not.
- Control whether the Python GIL should be held or released while calling the C++ method.
- Setting other flags or attributes that can direct how the generator will create the code for the wrapper of an item.
- Add additional items to the collection of extractor objects, such as new methods that don't actually exist in wx, items that will use existing methods to create a Python property, etc.
- In other words, if the generator needs to make a choice about how to generate code then the tweaker stage will be able to influence that choice by either changing the information coming from the extractors, or add additional information for the cases that need it.
- It is expected that many of the items being generated will not need much tweaking at all, just the special cases.
- Documentation items can also be changed here with similar techniques.
- Since the tweaker stage is plain Python code then some very creative things can be done if needed.
Generators
- After the extraction and tweaking has been done then a generator class can be instantiated to perform the transformation of the collection of extractor objects into the form needed by the Bindings Generator tool, (SWIG, SIP or whatever.)
- The generator chosen can be determined by a command line option, and the specifed code generator will be created by a factory function.
- By cleanly separating this step from the others it will be possible to switch between generators if needed, or to experiment with different approaches without affecting the default code production tool.
- There is a debug generator that simply dumps out an easy to read representation of the collection of extractor objects.
- Again the code for doing this step will likely be just a few lines in each of the ETG scripts, with most of the work being done in modules imported from the builder package.
- Creating and running the documentation generator is the final step in the ETG scripts and it follows the same pattern of the code generators. A factory function is used to select which doc generator is created and it will be possible to experiment with various back-ends without impacting the one being used in production.
Bindings Generator
Likely either SWIG or SIP, or perhaps both or neither.
Docs Generator
Likely Sphinx. http://sphinx.pocoo.org/
Here is the resulting doc: http://wxpython.org/Phoenix/docs/html/main.html
- The Docs Generator will take the documentation ouput from the ETG scripts, and will also need to be able to handle pulling docstrings out of the modules in wx.lib as well as processing some static docs for overviews and etc., (the other doc sources in the diagram) and making them all look like one consistent set of reference docs.
- It would be good to also include some official tutorials, how-to's and such. Some of these can probably be gleaned from the wiki and reworked a bit.