================
PyBlosxom README
================

:Author: PyBlosxom Development Team
:Version: $Id: README 1091 2007-07-27 04:21:43Z willhelm $
:Copyright: This document is distributed under the MIT license.

.. contents::


Summary
=======

PyBlosxom is a file-based blogging system in the spirit of Blosxom.
PyBlosxom uses directory tree to represent the category hierarchy.
All entries in a PyBlosxom blog are text files where the first
line is the title of the blog entry and the rest is the body of
the entry.

PyBlosxom isn't for everyone and it won't scale well if you have
a million entries.

PyBlosxom runs as a CGI script.  It also runs as a WSGI application
and it probably runs fine under mod_python, though this is less 
well-tested.

PyBlosxom supports flavours to change the look and feel of your blog.

PyBlosxom supports plugins to modify the existing default behavior.


How to install PyBlosxom
========================

Look at the ``install_*.txt`` documents in the ``docs/`` directory.
Pick the one that matches the kind of installation you're looking
for.

If you're upgrading PyBlosxom versions, read ``CHANGELOG`` which will
describe the differences between PyBlosxom versions and point out
things that you'll need to do when upgrading from one version to
the next.


How to find comprehensive documentation
=======================================

There's a series of text files in the docs/ directory which comprise
the current state of the PyBlosxom manual at the time of this release.

The most current version of the manual can be found on the `PyBlosxom
web-site <http://pyblosxom.sourceforge.net/>`_ .


How to get help
===============

On our web-site we have information about our mailing lists.  Send
an email to our pyblosxom-users mailing list if you have questions
that you are unable to find answers to.


How to report bugs, send in patches, fix problems
=================================================

We really appreciate people helping out.  

If you discover a problem with PyBlosxom, please log it in our bug-tracker_.

.. _bug-tracker: http://sf.net/tracker/?atid=517918&group_id=67445

If you can additionally fix it, attach a patch file to the bug or
send the patch as an attachment to the pyblosxom-devel mailing list.
Please make sure to describe the details of the problem you are fixing.


How to run unit tests
=====================

We use nose_ for test discovery.  You'll need to have that installed to 
run our tests.

.. _nose: http://somethingaboutorange.com/mrl/projects/nose/

To run the tests, execute::

   nosetests --verbose --include unit
   nosetests --verbose --include functional

If you would like to add tests to the test suite, please do and send us
patches!
