Wiki

Hacking

sections
Building pygame.
Keeping up with developments.
Generating docs
Running tests
Code style
Writing tests.
Writing docs.
Documentation Tools

Notes for hacking, developing, and modifying pygame.

[edit]

Building pygame.

See the wiki page: Compilation to figure out how to compile pygame on different platforms.

[edit]

Keeping up with developments.

Try and discuss changes on the mailing list. Especially if you plan to do a big change, let other people know about it on the mailing list.

Most developers are not on irc all of the time - and some never. So if you need a more realtime chat try and organise a time on the mailing list. Email lets people communicate in their own time zones.

The svn wiki page has links to various tools... like an rss feed for changes, a web based svn browser, and also links to the build bot. So you can read the commit logs.

Commit logs are important to keep them short, and also to summarise the changes you have made.

[edit]

Generating docs

python makeref.py

The makeref.py program runs Sphinx to generate HTML docs and src/docs/{module}_doc.h C headers from reStructuredText source.

The reStructuredText .rst files are stored in the reST/source and reST/source/ref directories.

An online reStructuredText primer can be found at the Python site.

Sphinx specific markup is described in theSphinx Documentation.

The Python Sphinx package itself depends on Docutils, Jinja2, and Pygments.

For Python 2.x, installing Sphinx will also grab and install its dependencies.

Sphinx can be downloaded from PyPi or using easy-install.

For Python 3.x only the latest repository versions work.

Be sure to install Sphinx last so it does not grab the wrong dependency versions:

svn checkout http://svn.berlios.de/svnroot/repos/docutils/trunk/docutils
hg clone http://dev.pocoo.org/hg/pygments-main pygments
easy_install Jinja2==dev
hg clone http://bitbucket.org/birkenfeld/sphinx/ sphinx

[edit]

Running tests

To run the tests from the test subdirectory in the Pygame distibution:

    python run_tests.py

To run the tests from the pygame.tests module:

    python -m pygame.tests

In either case the --help command line option will give usage instructions:

Usage: 

Runs all or some of the test.xxxx_test tests.

$ run_tests.py sprite threads -sd

Runs the sprite and threads module tests isolated in subprocesses, dumping
all failing tests info in the form of a dict.

Options:
  -h, --help            show this help message and exit
  -i, --incomplete      fail incomplete tests
  -n, --nosubprocess    run everything in a single process  (default: use
                        subprocesses)
  -T T, --timings=T     get timings for individual tests. Run test T times,
                        giving average time
  -e EXCLUDE, --exclude=EXCLUDE
                        exclude tests containing any of TAGS
  -w, --show_output     show silenced stderr/stdout on errors
  -r, --randomize       randomize order of tests
  -S SEED, --seed=SEED  seed randomizer
  -d, --dump            dump failures/errors as dict ready to eval
  -F FILE, --file=FILE  dump failures/errors to a file
  -a, --all             dump all results not just errors eg. -da
  -m THREADS, --multi_thread=THREADS
                        run subprocessed tests in x THREADS
  -t SECONDS, --time_out=SECONDS
                        kill stalled subprocessed tests after SECONDS
  -f DIR, --fake=DIR    run fake tests in run_tests__tests/$DIR
  -p PYTHON, --python=PYTHON
                        path to python excutable to run subproccesed tests
                        default (sys.executable): /usr/bin/python

[edit]

Code style

Try and follow the code style of the particular file you are editing.

Use 4 spaces instead of tabs, and Pep-8 generally. Make sure your editor doesn't insert tabs.

Try to keep things under 80 characters wide.

Try not to mix in white space commits with other code commits. This makes reading diffs easier if you separate the whitespace updates from the actual changes.

[edit]

Writing tests.

Tests are in the test/ directory.

Please see test/README.txt for more of a description on the tests, and the testing framework.

A naming convention is used for all tests. So from the name of a module, class, method, or function, you can find the tests for it.

Each module has a test file. eg. for pygame.surface there is test/surface_test.py

In that file there are methods for each of the classes, functions and methods. So Surface.blit has a 'test_blit' method. There can be multiple test methods for each method. eg. 'test_blit_keyword_args' in surface_test.py one of a few tests Surface.blit. Add extra words at the end of the method name to make multiple tests for the same method.

Methods named with todo at the front "todo_blit" are methods that need to be written. Or finished. By default all of the todo tests are skipped by the test runner. You can however, make the todo_ tests fail - to see how many more tests need to be finished.

Tests can use tags in order to organise them. There are optionally [modulename]_tags.py files for each module. A test/surface_tags.py file is used to specify tags for the pygame.surface module. You can use tags to skip tests on different platforms, or to choose different tests to exclude or run.

There are some test related tools + code in test/util/ .

To see if anything in a module is not documented... you can use: python compare_docs.py pygame.sprite sprite.doc

To generate some test stubs for your unittests from an existing file... you can do: python gen_stubs.py midi

[edit]

Writing docs.

Docs are in the lib/*.doc and src/*.doc files.

It uses a simple text based markup format which doesn't have many tags in it, and is easy to edit in a text editor.

Like source code it should be less than 80 collumns wide... but less than source code. Since it should be well formatted when you do: help(pygame.somemodule). As the help indents things, you might need to use 8-12 characters less per collumn 68 is a safe number. Have a look at your docs in the interpreter to make sure they look ok.

For new functions, or changes to old ones, you should note that the function is new at the bottom of the description... eg. 'New in pygame 1.9.1'

From the .doc files html is generated in the docs/ directory, and code to go in the src/pygamedocs.h file is generated with the makeref.py script.

Each function, method and object has some documentation for it.

Three line breaks after the previous entry.
There is the object being described. eg 'convert'
Then on the next line is a short one line description. eg 'change the pixel format of an image'
Then multiple lines describing how the method is called with the type of the argument. eg. 'Surface.convert(Surface): return Surface' 'Surface.convert(masks, flags=0): return Surface'
A line break after these ones.
Then paragraphs of further description. Describe what it does, and also how to use it. Explain any quirks, gotchas, or better alternatives.

Here is an example of the Surface.convert documentation. Everything between the quotes.

"""<END>

convert
change the pixel format of an image
Surface.convert(Surface): return Surface
Surface.convert(depth, flags=0): return Surface
Surface.convert(masks, flags=0): return Surface
Surface.convert(): return Surface

Creates a new copy of the Surface with the pixel format changed. The new pixel
format can be determined from another existing Surface. Otherwise depth,
flags, and masks arguments can be used, similar to the pygame.Surface() call.

If no arguments are passed the new Surface will have the same pixel format
as the display Surface. This is always the fastest format for blitting. It
is a good idea to convert all Surfaces before they are blitted many times.

The converted Surface will have no pixel alphas. They will be stripped if
the original had them. See Surface.convert_alpha() for preserving or creating
per-pixel alphas.
<END>"""

[edit]

Documentation Tools

Creating .doc files from modules:

python create_doc_from_py.py pygame.sprite

Find out what is not documented:

python compare_docs.py pygame.sprite sprite.doc

They're hidden in the test/util/ directory.

[edit]