Contributing to PyKDE
Prev |  | Next

### How PyKDE4 is Created

Very little of PyKDE4 is actually handwritten code - most of PyKDE4 is machine-generated from the KDE4 C++ header files, including all of the PyKDE4 class reference documentation. On a reasonably fast machine, it takes less than a minute to generate the basic PyKDE4 (including docs) - most of the development time is taken up doing test builds of PyKDE4, making a few minor bug fixes (usually to the code generation tool), and handwriting a small amount of code that can't be generated from templates or otherwise machine generated.

### What PyKDE4 Needs Help With

PyKDE4 includes around 600 different classes and about 10,000 different methods. While the machine-generated code is usually accurate and kdelibs (which underlies PyKDE4) is mature and thoroughly tested, there are always small bugs that creep in. In addition, first-time PyKDE4 users need assistance and information about constructing PyKDE apps or using PyKDE classes.

So where PyKDE4 really needs community assistance is in writing short example programs or longer tutorials for developing applications or using major subsystems included in PyKDE. A small number of examples are included in this release, but much of the PyKDE code has never been tested in actual use.

### Areas Where You Can Help

Example programs can be as short as a demo of a single widget, or as long as a full application. Nearly every class and widget in PyKDE4 could use a simple usage demo. In addition, example programs or tutorials would be helpful for the following areas:

- Using icons within a program in accordance with KDE reccomendations (KIcon, KIconLoader, KStandardDirs, etc)
- Configuration files and settings of apps (KConfig, KConfigSkeleton and related classes)
- Using KHTML and related support features (building a browser - see pykdedocs for a simple example)
- Using KBookmark and related classes
- Using KIO Slaves
- Using PyKDE's DOM facilities
- Using the Sonnet spellchecker
- Using KPLotWidget
- Using layout widgets in designing an application
- Using PyKDE widgets and classes with Qt Designer

There are almost certainly other kinds of example code, demos or tutorials that would be useful for PyKDE.

### What Are the Requirements for Example Code or Tutorials?

Basically any contributions in any form would be greatly appreciated. If you want your example code to function within the pykdedocs framework, the requirements for that are outlined below (but any examples are welcome).

Otherwise, there are only two requirements:

- The code has to work
- The code has to include a license statement that allows it to be distributed with PyKDE - either a GPL/LGPL license, a BSD-style license, or a declaration that the code is in public domain. The copyright and ownership of the code remains with the author, whose name and copyright notice should also be included.

### Writing Example Code for pykdedocs

pykdedocs (included in the PyKDE4 tarball distribution) incorporates example programs for classes as live (working) examples and simulataneously displays the source code for the example and the HTML docs for the class being demo'd. The examples for pykdedocs function like plugins to the program and should meet certain requirements. There is an example template (example_template.py) in the contrib/ directory of the tarball. The basic requirements are:

- helpText - there should be a global variable named 'helpText' that contains a brief string describing what the example does
- MainFrame - the main "window" of the program must be a class named 'MainFrame' and a subclass of KVBox.
- __main__ - the example program should have a '__main__' section so it can be run standalone

If the example isn't suitable for running within the pykdedocs framework, the example can include a button in the MainFrame window which allows the user to launch the example outside of pykdedocs (see dialog examples in pykdedocs for how to do it).

### Writing Tutorials for pykdedocs

Tutorials also have few requirements. The main requirements are that they include both runnable code and HTML text. In addition, to work with pykdedocs, all of the files (.html and .py) should fit under a single top level directory which will become a subdirectory of Tutorials/ in the PyKDE4 distribution. Other subdirectories can exist under the top level directory for the tutorial, but only HTML files in the top level directory will appear in pykdedocs tree view.

### Where Do Additional Contributions End Up?

Anything that isn't suitable for inclusion in the pykdedocs framework will be placed in the contrib/ directory that's part of the PyKDE4 distribution tarball.

### I Need a New Feature or Module in PyKDE4

Because of the difficulty in testing and verifying new features that might be added to PyKDE4, the following policy will be used: If a new feature or module seems appropriate, I'll generate the bindings and provide a modified tarball to the requestor. If in return I receive suitable example code to test, verify and demonstrate the feature's use, the feature will be included in PyKDE4 and maintained. If no suitable code is provided by the requestor, the feature won't be included in PyKDE4 or maintained for future releases.

Prev | Table of Contents | Next
Using PyKDE4 |  | Using the Class Reference