Skip to content

Commit

Permalink
Rewriting docs ..
Browse files Browse the repository at this point in the history
  • Loading branch information
@jpic
jpic committed Mar 9, 2013
1 parent c084431 commit 64026b0
Show file tree
Hide file tree
Showing 4 changed files with 417 additions and 167 deletions.
168 changes: 7 additions & 161 deletions README
View file
@@ -1,161 +1,13 @@
.. image:: https://secure.travis-ci.org/yourlabs/django-autocomplete-light.png?branch=master

django-autocomplete-light provides a micro framework, easing the implementation
of autocomplete widgets for Django projects.

Quick install
-------------

0. Install autocomplete box url and the staff debug url
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

- install the package with pip::

pip install django-autocomplete-light

- in ``urls.py``, call ``autocomplete_light.autodiscover()`` before
``admin.autodiscover()``, it can look like this:

.. code-block:: python

import autocomplete_light
# import every app/autocomplete_light_registry.py
autocomplete_light.autodiscover()

import admin
admin.autodiscover()

- install the autocomplete view and staff debug view in ``urls.py`` it can look
like this:

.. code-block:: python

urlpatterns = patterns('',
# [...] your url patterns are here
url(r'^autocomplete/', include('autocomplete_light.urls')),
)

- enable templates and static files by adding ``autocomplete_light`` to
``settings.INSTALLED_APPS``, it can look like this:

.. code-block: python

INSTALLED_APPS = [
# [...] your list of app packages is here, add this:
'autocomplete_light',
]

1. Install the javascript scripts
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

- load the javascript scripts after loading ``jquery.js``, it can look like this::

.. code-block:: django

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.js" type="text/javascript"></script>
{% include 'autocomplete_light/static.html' %}

- for admin support, install it in ``admin/base_site.html``, it could look like this::

.. code-block:: django

{% extends "admin/base.html" %}

{% block extrahead %}
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.js" type="text/javascript"></script>
{% include 'autocomplete_light/static.html' %}
{% endblock %}

.. note::

There is **nothing** magic in how the javascript loads. This means that you can
use ``django-compressor`` or anything.

Also, why are we not using ``Widget.Media`` ? See FAQ.

- register an Autocomplete for your model in
``your_app/autocomplete_light_registry.py``, it can look like this:

.. code-block:: python

import autocomplete_light
from models import Person

autocomplete_light.register(Person,
search_fields=['^first_name', 'last_name'])

- make the admin ``Order`` form that uses ``PersonAutocomplete``, in
``your_app/admin.py``:

.. code-block:: python

from django.contrib import admin
import autocomplete_light
from models import Order

class OrderAdmin(admin.ModelAdmin):
form = autocomplete_light.modelform_factory(Order)
admin.site.register(Order)

And that's it ! In the next section, we're doing the exact same thing but
without taking any shortcuts, teaching you how to override everything or use
autocompletes outside the admin.

3. Enable some autocomplete widgets for real
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

In this section, we're doing the same thing as in the previous section, but
without taking shortcuts. This should teach you how to override things.

- register an Autocomplete for your model in
``your_app/autocomplete_light_registry.py``, it can look like this:

.. code-block:: python

import autocomplete_light

from models import Person

class PersonAutocomplete(autocomplete_light.AutocompleteModel):
search_fields = ['^first_name', 'last_name'])

autocomplete_light.register(Person, PersonAutocomplete)

- now use ``PersonAutocomplete`` in a ``ChoiceWidget`` ie. for a
``ForeignKey``, it can look like this:

.. code-block:: python

from django import forms

import autocomplete_light

from models import Order, Person

class OrderForm(forms.ModelForm):
person = forms.ModelChoiceField(Person.objects.all(),
widget=autocomplete_light.ChoiceWidget('PersonAutocomplete'))

class Meta:
model = Order

- if using the admin, then register this form in the ModelAdmin, it can look
like this:

.. code-block:: python

from django.contrib import admin

from forms import OrderForm
from models import Order

class OrderAdmin(admin.ModelAdmin):
form = OrderForm
admin.site.register(Order, OrderAdmin)

Extra resources
---------------
django-autocomplete-light's purpose is to enable autocompletes quickly in a
django project. It was designed for Django so that every part overridable or
reusable independently. It is stable, tested, documented and fully supported:
it tries to be a good neighbour in Django ecosystem.

- `**Documentation** graciously hosted
<http://django-autocomplete-light.rtfd.org>`_ by `RTFD
<http://rtfd.org>`_
- `Live demo graciously hosted
<http://jpic.pythonanywhere.com/>`_ by `PythonAnywhere
<http://pythonanywhere.com/>`_,
Expand All @@ -168,12 +20,6 @@ Extra resources
- `Git graciously hosted
<https://github.com/yourlabs/django-autocomplete-light/>`_ by `GitHub
<http://github.com>`_,
- `Documentation graciously hosted
<http://django-autocomplete-light.rtfd.org>`_ by `RTFD
<http://rtfd.org>`_, you can also check the `cookbook
<https://django-autocomplete-light.readthedocs.org/en/docs_rewrite/cookbook.html>`_
which is part of the `docs_rewrite
<https://django-autocomplete-light.readthedocs.org/en/docs_rewrite/>`_ branch,
- `Package graciously hosted
<http://pypi.python.org/pypi/django-autocomplete-light/>`_ by `PyPi
<http://pypi.python.org/pypi>`_,
Expand Down
41 changes: 35 additions & 6 deletions docs/source/index.rst
View file
Expand Up @@ -6,13 +6,34 @@ README

.. include:: ../../README.rst

Full documentation
------------------
Install
-------

Click on any instruction step for details.

.. toctree::
:maxdepth: 3

install

If you didn't click any, and this is your first install: bravo !

Tutorial
--------

Learn the concepts by doing useful things.

.. toctree::
:maxdepth: 5

tutorial

Topics
------

.. toctree::
:maxdepth: 1
:maxdepth: 2

demo
quick
template
navigation
Expand All @@ -25,8 +46,16 @@ Full documentation
django13
debug

Javascript API
--------------
FAQ
---

.. toctree::
:maxdepth: 2

faq

API
---

- `autocomplete.js
<_static/autocomplete.html>`_
Expand Down
90 changes: 90 additions & 0 deletions docs/source/install.rst
View file
@@ -0,0 +1,90 @@
Install the package with pip
----------------------------

Install the stable release::

pip install django-autocomplete-light

Or the development version::

pip install -e git+https://github.com/yourlabs/django-autocomplete-light#egg=autocomplete_light

Append ``'autocomplete_light'`` to ``settings.INSTALLED_APPS``
--------------------------------------------------------------

Enable templates and static files by adding ``autocomplete_light`` to
``settings.INSTALLED_APPS``, it can look like this:

.. code-block:: python
INSTALLED_APPS = [
# [...] your list of app packages is here, add this:
'autocomplete_light',
]
Call ``autocomplete_light.autodiscover()`` *before* ``admin.autodiscover()``
----------------------------------------------------------------------------

In ``urls.py``, call ``autocomplete_light.autodiscover()`` before
``admin.autodiscover()``, it can look like this:

.. code-block:: python
import autocomplete_light
# import every app/autocomplete_light_registry.py
autocomplete_light.autodiscover()
import admin
admin.autodiscover()
Include ``autocomplete_light.urls``
-----------------------------------

Install the autocomplete view and staff debug view in ``urls.py`` it can look
like this:

.. code-block:: python
urlpatterns = patterns('',
# [...] your url patterns are here
url(r'^autocomplete/', include('autocomplete_light.urls')),
)
Ensure understanding of ``django.contrib.staticfiles``
------------------------------------------------------

Ensure that you understand django-staticfiles, if you don't try this article.

Include ``autocomplete_light/static.html`` after loading jquery.js
------------------------------------------------------------------

Load the javascript scripts after loading ``jquery.js``, it can look like this:

.. code-block:: django
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.js" type="text/javascript"></script>
{% include 'autocomplete_light/static.html' %}
Optionnaly include it in ``admin/base_site.html`` too
-----------------------------------------------------

For admin support, install it in ``admin/base_site.html``, it could look like
this:

.. code-block:: django
{% extends "admin/base.html" %}
{% block extrahead %}
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.js" type="text/javascript"></script>
{% include 'autocomplete_light/static.html' %}
{% endblock %}
.. note::

There is **nothing** magic in how the javascript loads. This means that you can
use ``django-compressor`` or anything.

.. info::

Also, why are we not using ``Widget.Media`` ? See FAQ.

0 comments on commit 64026b0

Please sign in to comment.