From bd034e383844810176220f582f090e6502a05b1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jorge=20C=2E=20Leit=C3=A3o?= Date: Sun, 11 May 2014 22:14:48 +0200 Subject: [PATCH] Improved README. --- README.rst | 142 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 82 insertions(+), 60 deletions(-) diff --git a/README.rst b/README.rst index 58b3996..22ecf78 100644 --- a/README.rst +++ b/README.rst @@ -1,44 +1,80 @@ -Xapian-Haystack -- A backend for Django-Haystack -================================================ +Xapian backend for Django-Haystack +================================== -Overview --------- -xapian-haystack is a backend for use with the Django Haystack search API and the Xapian search engine. +.. image:: https://travis-ci.org/jorgecarleitao/xapian-haystack.svg?branch=master + :target: https://travis-ci.org/jorgecarleitao/xapian-haystack -* More information on Haystack can be found here: `haystacksearch.org `_. -* More information on Xapian can be found here: `xapian.org `_. +.. _Django-Haystack: http://haystacksearch.org/ + +.. _Xapian: http://xapian.org + +Xapian-haystack is a backend of Django-Haystack_ for the Xapian_ search engine. +Thanks for checking it out. + +.. _here: http://getting-started-with-xapian.readthedocs.org/en/latest/index.html + +Haystack is an API for searching in Django websites. xapian-haystack is +a bridge from Haystack, the API, to Xapian, a search engine. + +Xapian is a powerful search engine written in C++ that uses probabilistic measures +to efficient search on text. More useful information can be found here_ (read the docs). Requirements ------------ -- Python 2.4 (May work with 2.3, but untested) -- Django 1.0.x +.. _yet: http://trac.xapian.org/ticket/346 + +- Python 2.4+ (Python 3.3 not support yet_). +- Django 1.5+ - Django-Haystack 2.0.X -- Xapian 1.0.13+ (May work with earlier versions, but untested) +- Xapian 1.0.13+ -Notes ------ +.. _Travis: -- Due to an issue with mod_python possibly causing deadlocks with Xapian (`issue #364 `_), when Python is not invoked through the "main interpreter", mod_python is not supported with xapian-haystack. It may work, with some tweaking, but your mileage will vary. +In particular, the backend is built on Travis_ using: -- Because Xapian does not support simultaneous ``WritableDatabase`` connections, it is *strongly* recommended that users take care when using ``RealTimeSearchIndex``. If there is a possibility of simultaneous write attempts on the database, keep in mind that they are likely to trigger multiple reindex attempts on the search index. If this occurs an `DatabaseLockError` exception will be raised by Xapian. To avoid this, either set ``WSGIDaemonProcess processes=1`` or use some other way of ensuring that there are not multiple attempts to write to the indexes. Alternatively, use ``SearchIndex`` and a cronjob to reindex content at set time intervals (sample cronjob can be found `here `_) or derive your own ``SearchIndex`` to implement some other form of keeping your indexes up to date. A good alternative is to use a `QueuedSearchIndex `_. +- Python 2.7.6 +- Django 1.6.4 +- Django-Haystack (latest) +- Xapian 1.2.8 (libxapian22) + +Features +-------- + +Xapian-Haystack provides all the standard features of Haystack: + +- Weighting +- Faceted search (date, query, etc.) +- Sorting +- Spelling suggestions + +.. _stemmer: https://en.wikipedia.org/wiki/Stemming + +Additionally, Xapian also uses a stemmer_ to create its index, +with support to different languages. Installation ------------ -#. Copy or symlink ``xapian_backend.py`` into ``haystack/backends/`` or install it by running one of the following commands: +.. _`this gist`: https://gist.github.com/jleclanche/ea0bc333b20ef6aa749c - ``python setup.py install`` +First, you need to install Xapian in your machine. +We recommend installing it on the virtual environment using `this gist`_. +First you activate the virtual environment, and them run the script. - or +You can test the installation was successful by running:: - ``pip install xapian-haystack`` + python -c "import xapian" - or +Finally, install Xapian-haystack by running:: - ``easy_install xapian-haystack`` + pip install git+https://github.com/jorgecarleitao/xapian-haystack.git -#. Set to something similar to: +Configuration +------------- + +Xapian is configured as other backends of Haystack. +You have to define the connection to the database, which is done to a path to a directory, e.g:: HAYSTACK_CONNECTIONS = { 'default': { @@ -47,67 +83,53 @@ Installation }, } -Configuration -------------- + .. _languages: http://xapian.org/docs/apidoc/html/classXapian_1_1Stem.html -As well as the flags described `here `_, the xapian backend includes two additional variables: +The backend includes the following settings: - - `HAYSTACK_XAPIAN_FLAGS` -- used to further configure how indexes are stored and manipulated. By default, this value is set to `FLAG_PHRASE | FLAG_BOOLEAN | FLAG_LOVEHATE | FLAG_WILDCARD | FLAG_PURE_NOT`. See the `Xapian::QueryParser::feature_flag in the Xapian documentation `_ for further explanation of the available Xapian.QueryParser flags. +- `HAYSTACK_XAPIAN_LANGUAGE`: the stemming language. By default is english, the list of available languages + can be found `here `_. - - `HAYSTACK_XAPIAN_WEIGHTING_SCHEME` -- used to override the default weighting scheme used during search. `HAYSTACK_XAPIAN_WEIGHTING_SCHEME` is assumed to be a tuple that corepsonds to the arguments to a BM25Weight constructor. See `Xapian::BM25Weight::BM25Weight in the Xapian documentation `_ for further information. +- `HAYSTACK_XAPIAN_WEIGHTING_SCHEME` - sets the weighting scheme used during search. + See the default scheme in the source code or see `Xapian::BM25Weight::BM25Weight in the Xapian documentation `_ + for further information. - - `HAYSTACK_XAPIAN_LANGUAGE` -- used to override the default stemming language. By default, Xapian will stem all terms in english. +- `HAYSTACK_XAPIAN_FLAGS`: used to further configure how indexes are stored and manipulated. + By default, this value is set to `FLAG_PHRASE | FLAG_BOOLEAN | FLAG_LOVEHATE | FLAG_WILDCARD | FLAG_PURE_NOT`. + See the `Xapian::QueryParser::feature_flag in the Xapian documentation `_ + for further explanation of the available Xapian.QueryParser flags. Testing ------- -The easiest way to test xapian-haystack is to symlink or copy the ``xapian_haystack/tests`` folder into the haystack/tests folder so that your source tree resembles this layout:: - - django-haystack - | - +---haystack - | | - | +---backends - | | - | +---solr_backend.py - | +---whoosh_backend.py - | +---xapian_backend.py - +---tests - | - +---core - | | - | +---[...] - | - +---[...] - | - +---xapian_tests - | | - | +---[...] - | - +---xapian_settings.py - -Once this is done, the tests can be executed in a similar fashion as the rest of the Haystack test-suite:: - - django-admin.py test xapian_tests --settings=xapian_settings - +Xapian-Haystack has a test suite in continuous deployment in Travis_. The script `.travis.yml` contains +all the steps to run the test suite on your machine. Source ------ -The latest source code can always be found here: `github.com/notanumber/xapian-haystack `_ +.. _github: http://github.com/jorgecarleitao/xapian-haystack/ + +The source code can be found in github_. Credits ------- -xapian-haystack is maintained by `David Sauve `_, and was originally funded by `Trapeze `_. +This fork of xapian-haystack is maintained by Jorge C. Leitão but +`David Sauve `_ was the main contributor of Xapian-Haystack; +Xapian-haystack was originally funded by `Trapeze `_. License ------- -xapian-haystack is Copyright (c) 2009, 2010, 2011, 2012 David Sauve, 2009, 2010 Trapeze. It is free software, and may be redistributed under the terms specified in the LICENSE file. +Xapian-haystack is Copyright (c) 2009, 2010, 2011, 2012 David Sauve, 2009, 2010 Trapeze and 2014 by Jorge C. Leitão. +It is free software, and may be redistributed under the terms specified in the LICENSE file. Questions, Comments, Concerns: ------------------------------ Feel free to open an issue here: `github.com/notanumber/xapian-haystack/issues `_ -Alternatively, ask questions on the django-haystack `mailing list `_ or `irc channel `_. +or pull request your work. + +You can ask questions on the django-haystack `mailing list `_ +or in the `irc channel `_.