Installing ztm.navigator

The simplest way is simply to declare a depency on ztm.navigator from your package. You do this by adding it to the install_requires parameter to the setup function in setup.py like this:

from setuptools import setup

setup( name='your-package',
       version='1.0',
       description='Your package',
       author='You',
       author_email='you@your.domain',
       url='http://your.domain/packaged/your-package/',
       packages=['your-package'],
       # This line is here because ztm.navigator as of 0.8 has not been uploaded to PyPI
       dependency_links=[ "http://ztmproject.org/snapshots/" ],
       install_requires=['ztm.navigator']
       )

The two interesting lines are dependency_links and install_requires.

Note

Setuptools is an extension of distutils, the standard way to package and distribute Python modules. We only use it through buildout which builds on setuptools.

The individual responsibilities of this trio can be confusing as they are tightly interwoven. You may think of their responsibilities like this:

• buildout runs the recipes defined in buildout.cfg
  • the recipes configure the package and populates the bin/ folder.
  • it calls setuptools
• setuptools checks the package setup.py and calculates all dependencies
• setuptools tries to retrieve the packages from PyPI and the web.
• setuptools uses metadata required by distutils

Occasionally you’ll also see virtualenv mentioned. It is used to isolate your instances from whatever is installed as extras in the Python interpreter you are using.

Now you can build or set up your package and the latest ztm.navigator and its dependencies will be retrieved automatically.

Extending and developing

You need the source code to run tests, generate documentation, debug, fix bugs or modify ztm.navigator itself. It can be branched from the mirror-repository at launchpad.net:

$ bzr branch lp:ztm.navigator

You should now have a copy of ztm.navigator in a folder called ztm.navigator

Setting up the package

ztm.navigator includes buildout configuration that will configure scripts for running tests, extraction of internationalization data, building and testing documentation.

Note

navigator 0.8 requires Python 2.5 or 2.4. Higher versions of Python not supported.

Enter the directory you branched above (navigator) to and bootstrap the buildout:

$ cd ztm.navigator
$ python --version
Python 2.5.4
$ 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.navigator package (creates a bin/ folder and places a buildout script there) . To set up the package you need to run:

$ bin/buildout

Note

Depending on your bandwidth this step may take a while the first time you as are downloading quite a few packages.

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

Let it look something like this:

[buildout]
eggs-directory=/Users/arnarl/.buildout/eggs

Simply run this script again if you change any dependencies. If you need more recent packages than the ones you’ve got installed, use the -n flag like this:

$ bin/buildout -n

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.navigator/src/ztm/navigator/tests. You can use the testrunner scripts to execute them:

$ bin/tests

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

Including ztm.navigator as a develop-egg

To see your changes in effect before you package the sources you should use a develop-egg.

To do this you need to register it as a develop-egg in the package you are including ztm.navigator from.

Open its buildout.cfg and add a line pointing to the directory you branched ztm.navigator to below the develop-eggs lines in the [buildout] section like this:

[buildout]
develop = .
          /home/arnarl/code/ztm.navigator

(You can use relative paths.)

Now run buildout again:

$ bin/buildout

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.

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 .po with new strings by running:

$ bin/i18nextract

Generating the documentation

Documentation is included in the package. It is written using reStructuredText, a format defined by Python’s distutils, and generated using sphinx. You can find the texts in ztm.navigator/src/ztm/navigator/doc.

HTML versions can be generated by running:

$ bin/sphinx-build src/ztm/navigator/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.

To get a PDF-file with the documentation:

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

To ensure that code examples in the documentation is correct you can run:

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

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

API documentation

API documentation is automatically generated when the zope.apidoc module is included and can be found at /++apidoc++/ of your site. You should only include this when developing and not when deploymed into production.

Assembling an egg

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

$ python setup.py bdist_egg

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