==================
 PyBlosxom Readme
==================

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.

PyBlosxom runs as a CGI script and WSGI application.

PyBlosxom can run as a "static renderer" and compile your blog into
HTML pages for any web server.  This is a good solution for blogs with
millions of entries or servers that are really slow or don't have a
way to run applications.

PyBlosxom supports templates (called 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 from a previous PyBlosxom version, read
``CHANGELOG`` which will describe the differences between PyBlosxom
versions and tell you things you need to change.


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.bluesock.org/>`_ .


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.

Some of us hang out on IRC on Freenode in ``#pyblosxom``.


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

We really appreciate people helping out.

If you discover a problem with PyBlosxom, please let us know on IRC
(#pyblosxom on freenode.net) or on the mailing lists.

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.
When sending a patch, **please** make sure to describe the details of 
the problem you are fixing.


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

Tests are written with the Python unittest module.

To run core tests, do this::

    python setup.py test

This will build PyBlosxom, then run the tests.

To run plugin unit tests do this::

    PYTHONPATH=. python plugins/testrunner.py

That will run all the plugins tests.

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