Developing ztm.topicmaps

To debug, fix bugs or extend ztm.topicmaps you first need the source itself. It can be branched from the mirror repository at launchpad.net:

$ bzr branch lp:ztm.topicmaps

Often you will want to include ztm.topicmaps from another package rather than developing it standalone. This is typically done by editing buildout.cfg in the other package you are using. Add the path to ztm.topicmaps to the develop-eggs lines in the [buildout] section. Next run buildout in the other package and your ztm.topicmaps branch is now a develop-egg for the other package. Any changes you make in your branch will be picked up the next time you restart that instance or run tests.

Note

Installation instructions for a full ZTM-package with web server, other infrastructure and development environment can be found in the top-level installation documentation.

Setting up the package

ztm.topicmaps includes buildout configuration that configures a test runner, internationalization scripts and documentation generation.

Note

If you intend to work a lot with Python-eggs and zc.buildout, you probably want to configure ~/.buildout/default.cfg in your home directory so that already downloaded eggs are not downloaded and compiled again and again for each package.

Note

ztm.topicmaps 0.8.1 is bound to the Zope Toolkit and works with Python versions 2.4, 2.5 and 2.6. We strongly recommend using 2.6 as we hope to drop 2.4 support before 1.0.

Enter the directory you branched ztm.topicmaps to and bootstrap zc.buildout:

$ cd ztm.topicmaps
$ python -S bootstrap.py

Warning

There may be problems with the default Python instance included in your distribution. If you experience problems please try compiling Python yourself. (On Windows the standard python.org binaries should be fine.)

This will bootstrap a buildout setup inside the ztm.topicmaps package (creates a bin/ folder and places a buildout script there) . To set up the package you need to run:

$ bin/buildout

Run this script again if you change any dependencies.

Running tests

To reduce the likelihood that your changes interfere or break other functionality you should always run the unit tests after doing any changes.

Unit tests are mostly found in ztm.topicmaps/src/ztm/topicmaps/tests. You can use the testrunner scripts to execute them:

$ bin/tests

If you submit a bug-fix, we also would very much appreciate a unit-test that demonstrates the problem along with the patch. If you wish to contribute new functionality to ztm.topicmaps please write unit tests covering the new features so others can avoid breaking them.

To check test coverage you may use:

$ bin/tests --coverage=coverage

Coverage statistics will be printed and details for each file will be printed in the ztm.topicmaps/parts/test/coverage/.

Extracting strings for translation

Some strings and web pages in ztm.topicmaps are shown to end users and need to be translated.

ztm.topicmaps uses zope.i18n which is built on GNU gettext. You can update the .pot with new strings by running:

$ bin/i18nextract

The .pot is found in ztm.topicmaps/src/ztm/topicmaps/locales.

Now you can use editors like poedit to update the different translations.

Generating the documentation

Documentation source is included in the package. It is written using reStructuredText and generated using Sphinx. You can find the texts in ztm.topicmaps/src/ztm/topicmaps/doc.

The buildout configuration does not generate a script to build the documentation by default since the extra dependencies are not needed for normal operation. You can create the scripts by running:

$ bin/buildout install documentation

This will download extra dependencies like Spinx itself, docutils, required plugins and construction scripts.

To ensure that example code in the documentation is correct you should run:

$ bin/sphinx-build -b doctest src/ztm/topicmaps/doc parts/doctest

HTML versions can be generated by running:

$ bin/sphinx-build src/ztm/topicmaps/doc parts/documentation

This will create a mini-website inside ztm.topicmaps/parts/documentation/. You can view it by pointing your web-browser to the directory.

Note

To get a simple local webserver try changing your working directory to parts/documentation and run:

$ python -m SimpleHTTPServer

You can now browse the documentation on port 8000 of localhost or port 8000 on whatever machine you are using. (Beware of firewalls and don’t open this to the world. You can shut down the server by pressing Ctrl-c)

We haven’t put any work into making the PDF-version look good, but you can generate it like this:

$ bin/sphinx-build -b pdf src/ztm/topicmaps/doc parts/documentation

Feel free to extend and improve the docs directly or send us comments about things that are unclear and needs improvements.

API documentation is automatically generated when the zope.apidoc module is included and can be found at /++apidoc++/ of your site.

Creating an egg

You can create your own eggs if you need changes that are not in the public eggs:

$ python setup.py sdist

You can also create Python version specific eggs:

$ python setup.py bdist_egg

The eggs are now available in the :file:ztm.topicmaps/dist folder. If you are making a new release, remember to update the version number in setup.py.