source: narcissusplugin/0.11/README.txt

 Trac Narcissus Plugin
---------------------

Description
===========

Narcissus is a plugin for Trac that provides an interactive visualisation
for mirroring the activities of small groups over a period of months.
The activities are measured differently for each resource. Contributions to 
the wiki and Subversion repository are measured according to the number of 
added lines. Tickets are scored according to the type of activity, such as 
creating, accepting, and resolving tickets, as well as adding comments at 
different stages of the task.

Users have the ability to control the value placed in each activity. The
underlying measures of the visualisations are very simple; it is important 
that this is clear to the users. 


Requirements
============

The narcissus plugin requires the Python Imaging Library (PIL) to
produce PNG images, and must be installed on your system. It can 
be downloaded from http://www.pythonware.com/products/pil.


Optional requirements
=====================

Any TrueType font may be used for the narcissus visualisations. Microsoft's
TrueType core fonts can be downloaded from http://corefonts.sourceforge.net/
for Linux and from http://web.nickshanks.com/typography/corefonts for Mac
or Windows systems.


Installation via Source
=======================

The installation of the narcissus plugin from source is done by
creating a Python egg distribution file and copying the .egg file to
the Trac plugins directory. Detailed information on Python eggs can be
found at http://peak.telecommunity.com/DevCenter/PythonEggs. In
addition, the Easy Install package is required to create Python
eggs. See http://peak.telecommunity.com/DevCenter/EasyInstall for more
information on using and installing Easy Install.

Checkout the source code for the narcissus plugin from:
http://praxis.it.usyd.edu.au/svn/kim/hons/Project/narcissus-plugin

Change to the narcissusplugin/0.10 directory and run:

python setup.py bdist_egg

This will generate a python egg in the dist directory. Copy the egg
file into the trac/plugins directory and follow the Configuration
steps outlined below.

We are currently looking at adding the narcissus plugin to the
swapoff repository hosted by http://trac-hacks.org/ in the future,
as the plugin matures.

Configuration
=============

Once the narcissus plugin has been installed either via source or via a
python egg, some configuration is needed before it can be used.

A new section called narcissus should be added to the conf/trac.ini
file with these fields:

cache_dir - The directory that will be used to cache the 
            generated images.

cache_manager - If this entry exists in the configuration file,
            then the cache management logic will be invoked
            and the cache_max_size, cache_min_size,
            cache_max_count and cache_min_count must be
            defined.

cache_max_size - The maximum size in bytes that the cache should
            consume. This is the high watermark for disk space
            used.

cache_min_size - When cleaning out the cache, remove files until
            this size in bytes is used by the cache. This is
            the low watermark for disk space used.

cache_max_count - The maximum number of files that the cache should
            contain. This is the high watermark for the directory
            entry count.

ttf_path - The path (including directory and filename) of the
            TrueType font to be used for visualisation. Optional.

The cache_dir directory must exist and the Trac server must have read
and write access.

The cache manager is an attempt at keeping the cache directory under
control. This is experimental code that may cause more problems than
it fixes. The cache manager will be invoked only if a new Narcissus
image is to be produced. If the image can be loaded from the cache,
then the cache manager shouldn't need to run. This should minimize the
I/O performance impact on the trac server. When the cache manager
determines that it should clean up the cache, it will delete files
based on the file access time. The files that were least accessed will
be deleted first.

Note: it is also recommended that the restrict_owner field under the 
ticket section of the configuration file should be set to true, in 
order to get the most out of the ticket view of the visualisation:

[ticket]
restrict_owner = true


Configuration Example
+++++++++++++++++++++

Here is a sample narcissus section:

[narcissus]
cache_dir = /tmp/trac/htdocs/narcissus
cache_manager = yes
cache_max_size = 10000000
cache_min_size = 5000000
cache_max_count = 2000
cache_min_count = 1500
ttf_path = /usr/share/fonts/truetype/msttcorefonts/arial.ttf

Note: /tmp may be cleaned after reboot depending on your platform and 
system preferences, which implies that the cache directory would need 
to be recreated after a reboot if it has been set to the above example.

The cache manager is turned on since there is an entry in the narcissus
section called cache_manager. The value doesn't matter. To turn off
the cache manager, simply comment out the cache_manager entry.

When the size of all the files in the cache directory exceeds
10,000,000 bytes or the number of files in the cache directory exceeds
2,000, then files are deleted until the size is less than 5,000,000
bytes and the number of files is less than 1,500.

Here's the same example but for Windows systems:

[narcissus]
cache_dir = C:\projects\plugins\env\trac\htdocs\narcissus
cache_manager = yes
cache_max_size = 10000000
cache_min_size = 5000000
cache_max_count = 2000
cache_min_count = 1500
ttf_path = C:\windows\fonts\arial.ttf


Contributors
============

Some of the source code in the narcissus plugin was adapted from:

 * Trac/Timeline.py, Copyright (c) Edgewall Software
 * The graphviz plugin, Copyright (c) Peter Kropf
 * The peerreview plugin, Copyright (C) Team5
 
Many thanks to Trent Apted for random smatterings of help and advice.