Developers
==========
This section is intended for developers of the Python AVM Library.

To obtain a source distribution go to the project website at
http://code.google.com/p/python-avm-library/source/checkout and follow the
instructions to checkout the most recent version. You may also find source
distribution for specific releases at
http://code.google.com/p/python-avm-library/downloads/list.

Overview of Source Distribution
-------------------------------

 * ``docs_src/`` -- Source code for documentation.
 * ``libavm/`` -- Source files for AVM Library
 * ``Makefile`` -- Makefile for producing documentation, distributions and cleaning directory.
 * ``setup.py`` -- Distutils configuration file.
 * ``MANIFEST.in`` -- Template for MANIFEST file used by Distutils.
 * ``test`` -- Tests


Documentation
-------------
Documentation is prepared using Sphinx Python Documentation Generator (see
http://sphinx.pocoo.org/). To make the documentation run the following command
in the root directory::

  make docs

This will create a directory ``docs/`` with HTML and PDF version of the
documentation. If more formats need to be created, edit the ``Makefile`` in
the root directory.

To compile only a specific documentation version, go to ``docs_src/`` and
type::

  make <format>

where ``<format>`` is one of the supported Sphinx documentation formats.

Installing Sphinx is pretty easy, just run::

  sudo easy_install sphinx

See the source code of both libraries and also the documentation for examples
of how to write the documentation. Note that documentation is Python source
files is not automatically included, as you have to specify which classes
should go in the documentation.

Note that all documentation is produced in ``docs_src/`` and then parts are copied to the text files (e.g. ``CHANGES``,``README`` and ``INSTALL``).

Packaging a Distribution
------------------------
To package a distribution run::

  make sdist

This will prepare the documentation and use distutils to package together a
distribution that will be placed in ``dist/``.

To clean up files produced by packaging the distribution, run::

  make clean

This will remove all prepared documentation, build directories and
distribution files, so remember to move the just produced tar-ball before you
run a clean.

Running Tests
-------------
Test are run by issuing the command::

  make runtests

This will run ``test/test_all.py``.

Distribution Configuration
--------------------------
The file ``setup.py`` specify how the distribution is packed together. Most
important to note is that version in formation is read from ``VERSION`` file,
and that the file ``MANIFEST.in`` specifies which other files to include in
the distribution besides the Python source.

References for Developers
-------------------------
 * `ctypes <http://docs.python.org/lib/module-ctypes.html>`_
 * `Sphinx <http://sphinx.pocoo.org/contents.html>`_
 * `Distutils <http://docs.python.org/dist/dist.html>`_