==============
 About PyDitz
==============

Introduction
============

This package is intended to be a drop-in replacement for the Ditz_
distributed issue tracker.  It provides a ``pyditz`` command-line program,
which acts (mostly) the same way as ``ditz``, and it adds several other
nice things too:

* Whereas ``ditz``, when typed on its own, runs the ``todo`` command,
  ``pyditz`` drops you into a command shell where you can run Ditz commands
  and get completion on command names, issue names and release names
  according to context.

* With ``pyditz``, you don't have to run it from the same directory where
  the issue database is; it will look in parent directories for it.

* It keeps an intelligent cache of issues, so parsing of all the YAML files
  isn't necessary for each command.  This greatly improves speed when you
  have lots of issues.

* You can use the database engine of PyDitz in Python programs to migrate
  bug databases to and from Ditz format, or create summary reports in your
  own favourite format.  Me, I prefer reStructuredText_ and rst2pdf_.

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

To install and run it:
    PyYAML_ and Jinja2_

To run the test suite:
    Nose_, Mock_ and Coverage_

To build source distributions from the checked-out Mercurial_ repo:
    hgtools_

To build the documentation:
    Sphinx_ and the napoleon_ extension

Installation
============

The usual incantation will install things::

    python setup.py install

This will install the ``ditz`` module and a console command called
``pyditz`` to invoke in a similar manner to the original ``ditz``.

If you want to shadow the original completely, and have the ``ditz``
command run this instead, create a file called ``.ditzrc`` in your home
directory and add these lines::

    [install]
    command = ditz

This only takes effect at installation time.  Of course, instead of
``ditz`` you can choose anything else more keyboard-friendly.

Documentation
=============

The current documentation can be found online here__.

__ https://pythonhosted.org/pyditz

License
=======

PyDitz is distributed under the `GNU General Public License, v2`__.

__ https://gnu.org/licenses/old-licenses/gpl-2.0-standalone.html

.. _Coverage: https://pypi.python.org/pypi/coverage
.. _Ditz: http://ditz.rubyforge.org
.. _Jinja2: http://jinja.pocoo.org
.. _Mercurial: http://mercurial.selenic.com
.. _Mock: https://pypi.python.org/pypi/mock
.. _Nose: https://pypi.python.org/pypi/nose
.. _PyYAML: https://pypi.python.org/pypi/PyYAML
.. _Sphinx: http://sphinx.pocoo.org
.. _hgtools: https://pypi.python.org/pypi/hgtools
.. _napoleon: https://pypi.python.org/pypi/sphinxcontrib-napoleon
.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. _rst2pdf: https://pypi.python.org/pypi/rst2pdf
