documentation + setup stuff

README.md

@@ -3,9 +3,9 @@ Algolia Search for Django
 
 This package let you easily integrate the Algolia Search API to your favorite ORM. It's based on the [algoliasearch-client-python](https://github.com/algolia/algoliasearch-client-python) package. Both Python 2.x and 3.x are supported.
 
-You might be interested in the sample Django application providing a typeahead.js based auto-completion and Google-like instant search: (algoliasearch-django-example)[] (TODO)
+You might be interested in the sample Django application providing a typeahead.js based auto-completion and Google-like instant search: [algoliasearch-django-example](https://github.com/algolia/algoliasearch-django-example)
 
-TODO: travis + other badges
+[![PyPI version](https://badge.fury.io/py/algoliasearch-django.svg)](http://badge.fury.io/py/algoliasearch-django)
 
 Table of Content
 -------------
@@ -14,6 +14,11 @@ Table of Content
 1. [Install](#install)
 1. [Setup](#setup)
 1. [Quick Start](#quick-start)
+1. [Commands](#commands)
+1. [Search](#search)
+1. [Geo-search](#geo-search)
+1. [Options](#options)
+
 
 Install
 -------------
@@ -32,12 +37,16 @@ ALGOLIA_APPLICATION_ID = 'MyAppID'
 ALGOLIA_API_KEY = 'MyApiKey'
 ```
 
-TODO: speak about prefix/suffix usage
+There is also two optionals settings that take a string:
+
+* `ALGOLIA_INDEX_PREFIX`: prefix all index. You can use it to seperate different application, like `site1_Products` and `site2_Products`.
+* `ALGOLIA_INDEX_SUFFIX`: suffix all index. You can use it to differenciate development and production environement, like `Location_dev` and `Location_prod`.
+
 
 Quick Start
 -------------
 
-Simply call `AlgoliaSearch.register()` for each of the models you want to index. A good place to do this is in your application's AppConfig (generally your `app.py` file):
+Simply call `AlgoliaSearch.register()` for each of the models you want to index. A good place to do this is in your application's AppConfig (generally named `apps.py`).
 
 ```python
 from django.apps import AppConfig
@@ -51,41 +60,87 @@ class YourAppConfig(AppConfig):
         AlgoliaSearch.register(YourModel)
 ```
 
-By default, all the fields of your model will be used. You can configure the index by creating a subclass of `AlgoliaIndex`. A good place to do this is in a separeted file `index.py`:
+And then, don't forget the line below in the `__init__.py` file of your Django application.
+
+```python
+default_app_config = 'your_django_app.apps.YourAppConfig'
+```
+
+By default, all the fields of your model will be used. You can configure the index by creating a subclass of `AlgoliaIndex`. A good place to do this is in a separeted file, like `index.py`.
 
 ```python
 from AlgoliaSearch import AlgoliaIndex
 
 class YourModelIndex(AlgoliaIndex):
-    fields = ('name', 'date',) # default: all the fields of your model
-    geo_field = 'location' # tuple or callable that returns tuple (lat, lng)
-    settings = {'attributesToIndex': ['name']} # index settings
-    index_name = 'my_index' # default: model.__name__
+    fields = ('name', 'date')
+    geo_field = 'location'
+    settings = {'attributesToIndex': ['name']}
+    index_name = 'my_index'
 ```
 
-`fields` and `geo_field` can be a field or a callable.
-Please take a look at [the documentation about index settings](https://www.algolia.com/doc/python#Settings). `settings` is applied when the command `algolia_buildindex`, `algolia_reindex` or `algolia_applysettings` is executed.
+And then replace `AlgoliaSearch.register(YourModel)` with `AlgoliaSearch.register(YourModel, YourModelIndex)`.
 
+## Commands
+
+* `python manage.py algolia_buildindex`: index all the registered models. This one should be use the first time. Be careful, if the index already exist on Algolia, it will clear it first.
+* `python manage.py algolia_reindex`: reindex all the registered models. This command will first send all the record to a temporary index and then moves it when the build operation is completed. **We highly recommand this command in production environement.**
+* `python manage.py algolia_applysettings`: (re)apply the index settings.
+* `python manage.py algolia_clearindex`: clear the index
 
+## Search
 
+We recommend the usage of our [JavaScript API Client](https://github.com/algolia/algoliasearch-client-js) to perform queries directly from the end-user browser without going through your server.
 
+## Geo-Search
 
-## Setup
+Use the `geo_field` attribute to localize your record. `geo_field` can be a tuple or a callable that return a tuple (latitude, longitude).
 
-* Install via pip: `pip install algoliasearch-django`
-* In your `setting.py`, add `AlgoliaSearch` to the `INTALLED_APPS`
-* In the same file, adds to variable `ALGOLIA_APPLICATION_ID` and `ALGOLIA_API_KEY`
-* Register your model in your AppConfig
-* Run the command to index the models: `python manage.py algolia_buildindex`
+```python
+class Contact(models.Model):
+    name = models.CharField()
+    lat = models.FloatField()
+    lng = models.FloatField()
+
+    def location(self):
+        return (self.lat, self.lng)
 
-## Settings
 
-* `ALGOLIA_INDEX_PREFIX`: a prefix for all the index (useful for diff app)
-* `ALGOLIA_INDEX_SUFFIX`: a suffix for all the index (useful for dev/prod/test)
-* `ALGOLIA_APPLICATION_ID`: your application ID
-* `ALGOLIA_API_KEY`: your API key (need write access)
+class ContactIndex(AlgoliaIndex):
+    fields = 'name'
+    geo_field = 'location'
 
-## Commands
 
-* `./manage.py algolia_buildindex`: hard index all the models
-* `./manage.py algolia_reindex`: solf reindex all the models (create another index, send data, wait the indexing task and then rename the index)
+AlgoliaSearch.register(Contact, ContactIndex)
+```
+
+# Options
+
+## Custom `objectID`
+
+You can choose which field will be used as the `objectID`. The field should be unique and can be a string or integer. By default, we use the `pk` field of the model.
+
+```python
+class ArticleIndex(AlgoliaIndex):
+    custom_objectID = 'post_id'
+```
+
+## Custom index name
+
+You can customize the inde name. By default, the index name will be the name of the model class.
+
+```python
+class ContactIndex(AlgoliaIndex):
+    index_name = 'Entreprise'
+```
+
+## Index settings
+
+We provide many ways to configure your index allowing you to tune your overall index relevancy. All the configuration are explained on [our website](https://www.algolia.com/doc/python#Settings).
+
+```python
+class ArticleIndex(AlgoliaIndex):
+    settings = {
+        'attributesToIndex': ['name', 'description', 'url'],
+        'customRanking': ['desc(vote_count)', 'asc(name)']
+    }
+```

setup.cfg

@@ -0,0 +1,2 @@
+[bdist_wheel]
+universal=1

setup.py

@@ -45,7 +45,5 @@
         'Programming Language :: Python :: 2',
         'Programming Language :: Python :: 3',
         'Topic :: Internet :: WWW/HTTP',
-        'Topic :: Interne :: WWW/HTTP :: Dynamic Content',
-        'Topic :: Software Developement :: Libraries :: Python Modules'
     ]
 )