==============
 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 extend PyDitz using plugins that you write---either simple
  standalone files (similar to the ``ditz`` 'hook' feature), or packages
  that use setuptools_ entrypoints.

* 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_, Jinja2_ and six_

To have nice terminal highlighting output:
    Pygments_ (and colorama_ if you're on Windows)

To run the test suite:
    Nose_, Mock_ and Coverage_

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

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 ``ditz.cfg`` in a ``.ditz``
subdirectory of your home directory and add these lines::

    [config]
    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__.  You can also look at
an example of the `HTML output`_.

__ https://pythonhosted.org/pyditz

License
=======

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

__ http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html

Links
=====

If you like this, here's a few more things you might want to check out:

* Pitz_ is another Ditz-alike issue tracker, also written in Python.  Its
  bug database is not compatible with Ditz, and I didn't have much luck
  getting it to work, but it might work for you.

* There's another Python project of the same name called akaihola-pyditz_.
  (I only found it after publishing mine, or I might have chosen another
  name.)  Not updated for 6 years, but it has some ideas for logging work
  that might be useful.

* There's also `ditz plus plus`_, another reimplemenation written in C++,
  although that hasn't been updated since mid-2013.

* If you're a fan of `GNU Emacs`_, there's a ditz-mode_ written for it that
  I maintain.  It works with the original Ditz, or PyDitz.

.. _Coverage: https://pypi.python.org/pypi/coverage
.. _Ditz: http://rubygems.org/gems/ditz
.. _GNU Emacs: https://www.gnu.org/software/emacs
.. _HTML output: https://pythonhosted.org/pyditz/_static/index.html
.. _Jinja2: http://jinja.pocoo.org
.. _Mercurial: http://mercurial.selenic.com
.. _Mock: https://pypi.python.org/pypi/mock
.. _Nose: https://pypi.python.org/pypi/nose
.. _Pitz: https://github.com/mw44118/pitz
.. _Pygments: https://pypi.python.org/pypi/Pygments
.. _PyYAML: https://pypi.python.org/pypi/PyYAML
.. _Sphinx: http://sphinx.pocoo.org
.. _akaihola-pyditz: https://github.com/akaihola/pyditz
.. _colorama: https://pypi.python.org/pypi/colorama
.. _ditz plus plus: http://sourceforge.net/projects/ditz
.. _ditz-mode: https://bitbucket.org/zondo/ditz-mode
.. _flake8: https://pypi.python.org/pypi/flake8
.. _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
.. _setuptools: http://pythonhosted.org/setuptools
.. _six: https://pypi.python.org/pypi/six
