Improved README.
This commit is contained in:
Jorge C. Leitão
parent
6ed8569ef3
commit
bd034e3838
142
README.rst
142
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 <http://haystacksearch.org/>`_.
|
||||
* More information on Xapian can be found here: `xapian.org <http://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 <http://trac.xapian.org/ticket/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 <http://gist.github.com/216247>`_) 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 <http://github.com/toastdriven/queued_search>`_.
|
||||
- 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 <http://docs.haystacksearch.org/dev/settings.html>`_, 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 <http://xapian.org/docs/apidoc/html/classXapian_1_1QueryParser.html>`_ 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 <languages>`_.
|
||||
|
||||
- `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 <http://xapian.org/docs/apidoc/html/classXapian_1_1BM25Weight.html>`_ 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 <http://xapian.org/docs/apidoc/html/classXapian_1_1BM25Weight.html>`_
|
||||
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 <http://xapian.org/docs/apidoc/html/classXapian_1_1QueryParser.html>`_
|
||||
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 <http://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 <mailto:david.sauve@bag-of-holding.com>`_, and was originally funded by `Trapeze <http://www.trapeze.com>`_.
|
||||
This fork of xapian-haystack is maintained by Jorge C. Leitão but
|
||||
`David Sauve <mailto:david.sauve@bag-of-holding.com>`_ was the main contributor of Xapian-Haystack;
|
||||
Xapian-haystack was originally funded by `Trapeze <http://www.trapeze.com>`_.
|
||||
|
||||
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 <http://github.com/notanumber/xapian-haystack/issues>`_
|
||||
Alternatively, ask questions on the django-haystack `mailing list <http://groups.google.com/group/django-haystack/>`_ or `irc channel <irc://irc.freenode.net/haystack>`_.
|
||||
or pull request your work.
|
||||
|
||||
You can ask questions on the django-haystack `mailing list <http://groups.google.com/group/django-haystack/>`_
|
||||
or in the `irc channel <irc://irc.freenode.net/haystack>`_.
|
||||
|
|
|
|||
Loading…
Reference in New Issue