Commits

Germano Gabbianelli  committed cc8bd50

Added documentation made with sphinx.

  • Participants
  • Parent commits c362a62

Comments (0)

Files changed (11)

File docs/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf _build/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	@echo
+	@echo "Build finished. The HTML pages are in _build/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in _build/dirhtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in _build/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in _build/qthelp, like this:"
+	@echo "# qcollectiongenerator _build/qthelp/django-autocomplete.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile _build/qthelp/django-autocomplete.qhc"
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in _build/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	@echo
+	@echo "The overview file is in _build/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in _build/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in _build/doctest/output.txt."

File docs/conf.py

+# -*- coding: utf-8 -*-
+#
+# django-autocomplete documentation build configuration file, created by
+# sphinx-quickstart on Sun Nov 22 16:07:11 2009.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.append(os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'django-autocomplete'
+copyright = u'2009, Tyrion'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1-dev'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'django-autocompletedoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'django-autocomplete.tex', u'django-autocomplete Documentation',
+   u'Tyrion', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True

File docs/example.png

Added
New image

File docs/handling-relationships.rst

+Quickstart: Handling relationships
+==================================
+
+the Django AutoComplete's :class:`~autocomplete.fields.ModelChoiceField` can be
+used to handle relationships between models. It's a subclass of  the Django's
+`ModelChoiceField`_ and uses :class:`~autocomplete.widgets.AutoCompleteWidget`
+as the default widget.
+
+Let's assume we have a form to send a message to an user::
+
+    from django import forms
+    from django.contrib.auth.models import User
+
+    class MessageForm(forms.Form):
+        user = forms.ModelChoiceField(User.objects.all())
+        message = forms.CharField(widget=forms.Textarea)
+
+.. note::
+    
+    You could obtain the same form using a `ModelForm`_ with the
+    :class:`!django.contrib.auth.models.Message` model.
+    
+.. _`ModelChoiceField`: http://docs.djangoproject.com/en/dev/ref/forms/fields/#modelchoicefield
+.. _`ModelForm`: http://docs.djangoproject.com/en/dev/topics/forms/modelforms/#modelform
+
+
+Using AutoComplete with the Form
+--------------------------------
+
+But what if we have *a lot* of users?
+Finding the right one within a :class:`~forms.Select` would be frustrating and
+moreover would result in a heavy query (``SELCT * FROM auth_user``) every time
+the form is displayed. That's why we prefer to use AutoComplete::
+
+    from django import forms
+    from autocomplete import ModelChoiceField
+
+    class MessageForm(forms.Form):
+        user = ModelChoiceField('user')
+        message = forms.CharField(widget=forms.Textarea)
+
+The string ``'user'`` passed as the first parameter of
+:class:`~autocomplete.fields.ModelChoiceField` is an
+identifier used by autocomplete to select the correct choices-set to render.
+
+
+Defining a choices-set
+----------------------
+
+We must define this choices-set editing our URLConf as follows::
+
+    from django.contrib.auth.models import User
+    from autocomplete.views import autocomplete
+
+    autocomplete.register(
+        id = 'user',
+        queryset = User.objects.all(),
+        fields = ('username', 'email'),
+        limit = 5,
+    )
+
+This registers the ``user`` choices-set and maps to it a queryset containing all
+the users in our database (``User.objects.all()``). It will also filter the
+results by the ``username`` and ``email`` fields and display at most five users per
+query.
+
+
+Registering the autocomplete view
+---------------------------------
+
+Now to let AutoComplete serve our choices as json data, we have to register the
+autocomplete view::
+
+    urlpatterns = patterns('',
+        # your urls here ...
+        url('^autocomplete/(\w+)/$', autocomplete, name='autocomplete'),
+        # ... and other urls here.
+    )
+
+Ok. That's it. Just render the form in a template and enjoy.
+
+.. seealso::
+
+    :ref:`media-files-configuration`
+        for how to configure and customize the
+        Media files of your widget (including how to use `JQuery`_ or other js toolkits
+        with Django AutoComplete).
+
+.. _`JQuery`: http://jquery.com

File docs/handling-suggestions.rst

+Quickstart: Handling suggestions
+================================
+
+AutoCompleteWidget can be used to offer *suggestions* based on the user input.
+Let's assume for example that we have a Form to send mails to other users::
+
+    from django import forms
+
+    class SendMail(forms.Form):
+        to = forms.EmailField()
+        subject = forms.CharField(required=False)
+        content = forms.CharField(widget=forms.Textarea)
+
+
+Using AutoComplete with the Form
+--------------------------------
+
+Using this form the user has to manually enter the email address.
+With AutoCompleteWidget we can suggest an email address when the
+corresponding username is typed::
+
+    from django import forms
+    from autocomplete.widgets import AutoCompleteWidget
+
+    class SendMail(froms.Form):
+        to = forms.EmailField(widget=AutoCompleteWidget('emails',
+                                                        force_selection=False))
+        subject = forms.CharField(required=False)
+        content = forms.CharField(widget=forms.Textarea)
+
+The string ``'emails'`` passed as the first parameter of
+:class:`~autocomplete.widgets.AutoCompleteWidget` is an
+identifier used by autocomplete to select the correct choices-set to render.
+
+``force_selection=False`` tells the Widget to not force the user to select one
+of the displayed choices. We use this to allow the user to manually insert an
+email address, without selecting a suggestion.
+
+Defining the choices-set
+------------------------
+
+Now we have to register the ``emails`` choices-set editing our URLConf::
+
+    from django.conf.urls.defaults import *
+    from django.contrib.auth.models import User
+    from autocomplete.views import autocomplete
+
+    autocomplete.register(
+        id = 'emails',
+        queryset = User.objects.all(),
+        fields = ('username', 'email'),
+        limit = 5,
+        key = 'email',
+        label = 'email',
+    )
+
+.. note::
+
+    Since we are using an EmailField in our Form we **must** set the *key*
+    parameter to ``'email'``, otherwise the Form won't validate.
+
+..
+ In this way, when an user starts typing something (e.g. *bob*) all the
+ email addresses that starts with that will be shown (e.g. *bob1@example.com* and
+ *bob2@example.com*).
+..
+ But what happens if an user (e.g. *bob*) has an email address that doesn't start with
+ his username (e.g. iam.bob@example.com) when you start typing his username?
+..
+ But the suggestion won't show up if you start typing an username (e.g. *bob*) which has an
+ email address that doesn't match his username (e.g. *iam.bob@example.com*)
+
+..
+ But what if our user starts typing an username (e.g. *bob*) 
+ But what if *Bob* has an email address like *foo@bobhost.com*? In this case his
+ email address won't show up, because it doesn't start with *bob*. We can easily
+ fix this by adding ``'username'`` to the fields of our choices-set.
+
+In this way when the user starts typing either an username or an email address
+a set of suggested email addresses will show up.
+
+We'd also like to make the suggestion nicer, displaying the first and last name
+of the user as well as the email address. We can do this using a formatter
+function.
+
+Our choices-set becomes::
+
+    from django.conf.urls.defaults import *
+    from django.contrib.auth.models import User
+    from autocomplete.views import autocomplete
+
+    def display_suggestion(user):
+        return u"%s %s <%s>" % (user.first_name, user.last_name, user.email)
+
+    autocomplete.register(
+        id = 'emails',
+        queryset = User.objects.all(),
+        fields = ('username', 'email'),
+        limit = 5,
+        key = 'email',
+        label = display_suggestion,
+    )
+
+Registering the autocomplete view
+---------------------------------
+
+Now edit your URLConf again and add the *autocomplete* view to your urls::
+
+    urlpatterns = patterns('',
+        # your other urls here.
+        url('^autocomplete/(\w+)/$', autocomplete, name='autocomplete'),
+    )
+
+Ok. That's it. Just render the form in a template and enjoy.
+
+.. seealso::
+
+    :ref:`media-files-configuration`
+        for how to configure and customize the
+        Media files of your widget (including how to use `JQuery`_ or other js toolkits
+        with Django AutoComplete).
+
+.. _`JQuery`: http://jquery.com

File docs/index.rst

+Django AutoComplete Documentation
+=================================
+
+Django AutoComplete helps you providing `autocompletion`_ for your input tags.
+You can easily make Django AutoComplete work with any javascript toolkit,
+although only `YUI`_ and `JQuery`_ are supported by default.
+
+.. image:: example.png
+
+.. _`autocompletion`: http://developer.yahoo.com/ypatterns/selection/autocomplete.html
+.. _`YUI`: http://developer.yahoo.com/yui/
+.. _`JQuery`: http://jquery.com/
+
+
+.. toctree::
+
+   installation
+   handling-relationships
+   handling-suggestions
+
+   library/fields
+   library/views
+   library/widgets
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

File docs/installation.rst

+Installation
+============
+
+You can install Django AutoComplete with `pip`_ or `easy_install`_::
+
+    pip install django-autocomplete
+    easy_install django-autocomplete
+
+Alternatively you can download the `last stable release`_ from the Python
+Package Index and run :command:`python setup.py install` from a terminal to
+install it.
+
+.. _`pip`: http://pypi.python.org/pypi/pip/
+.. _`easy_install`: http://pypi.python.org/pypi/setuptools/
+.. _`last stable release`: http://pypi.python.org/pypi/django-autocomplete/
+
+Installing the development version
+----------------------------------
+
+To get the latest updates and bug fixes install the developement version.
+You can do this by cloning the Mercurial repository with::
+
+    $ hg clone http://bitbucket.org/tyrion/django-autocomplete/
+
+Then you have to put the :file:`autocomplete` directory under your
+``sys.path``.
+
+Getting the latest changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+To update your local repository run the following commands from the
+:file:`django-autocomplete` directory::
+
+    $ hg pull
+    $ hg update
+

File docs/library/fields.rst

+:mod:`autocomplete.fields` ModelChoiceField
+===========================================
+
+.. module:: autocomplete.fields
+
+.. _modelchoicefield:
+
+.. class:: ModelChoiceField(ac_name[, reverse_label[, view[, widget[, **kwargs]]]])
+
+    A form field similar to ``django.forms.ModelChoiceField``, which uses
+    an :class:`~autocomplete.widgets.AutoCompleteWidget` instead of a
+    ``forms.Select`` to render its choices.
+    If you do not specify a widget, :class:`ModelChoiceField` will instantiate
+    a new :class:`~autocomplete.widgets.AutoCompleteWidget` with the
+    ``ac_name`` and ``reverse_label`` parameters you provided.
+    If you want to use a customized version of
+    :class:`~autocomplete.widgets.AutoCompleteWidget` you must pass an
+    instance::
+        
+        ModelChoiceField('myac', widget=MyACWidget('myac', **custom_params))
+
+
+    *ac_name*
+        The id of a choice-set previously registered with the *view*.
+    
+    *reverse_label*
+        Whether to obtain the label of a choice from its key when rendering
+        the widget with an initial value, or not. This is always set to
+        True by default.
+
+    *view*
+        the view used to retrieve the choices, defaults to
+        :obj:`autocomplete.views.autocomplete`.
+
+    *widget*
+        the widget to use, defaults to
+        :class:`autocomplete.widgets.AutoCompleteWidget`.
+
+    *\*\*kwargs*
+        other keyword arguments that are passed to the Django's Widget.__init__
+        method.
+
+
+

File docs/library/views.rst

+:mod:`autocomplete.views` AutoComplete Views
+============================================
+
+.. module:: autocomplete.views
+
+
+.. class:: AutoCompleteView
+
+    The AutoCompleteView is called by an Ajax request when the user starts typing
+    [#]_ and returns a set of options, matching the user input, for the requested
+    choices-set. The output is encoded as JSON (``mimetype='application/json'``) and
+    consists of a list of *key-label* pairs::
+
+        # Request:
+        GET /autocomplete/fruit/?query=red
+        
+        # JSON Response:
+        [[9, "Strawberry"], [10, "Cherry"], [11, "Apple"]]
+
+    Since the AutoCompleteView is a class you can subclass it to customize its
+    behaviour. However a simple instance (:obj:`autocomplete.views.autocomplete`)
+    is made available, and it's used for the default value of the *view* argument in
+    :class:`~autocomplete.widgets.AutoCompleteWidget` and
+    :class:`~autocomplete.fields.ModelChoiceField`.
+
+    .. data:: settings
+
+        A ``dict`` containing the configuration of all the choices-sets
+        registered.
+
+
+    .. method:: __call__(request, ac_name[, query_param])
+        
+        This method makes AutoCompleteView's instances callable and thus usable
+        as views.
+
+        The optional argument *query_param* is the name of the GET parameter
+        that should contain the user input. It defaults to ``'query'``.
+
+        If the Javascript toolkit you're using requires you to use an other
+        value (e.g. ``'q'``) you can customize this param, by passing a
+        ``dict`` to the autocomplete view in your URLConf::
+
+            url('^autocomplete/(\w+)$', autocomplete, dict(query_param='q')),
+
+
+    .. method:: not_found(request, ac_name):
+        
+        Called when an user asks for an inexisting choices-set.
+        It must return an HttpResponse object for the client.
+
+
+    .. method:: forbidden(request, ac_name):
+        
+        Called when an user is not authorized to access a choices-set.
+        This means that the user is not authenticated and ``auth=True`` has
+        been set in the choices-set.
+        It must return an HttpResponse object for the client.
+
+    .. method:: reverse_label(ac_name, key_value)
+
+        Method used to obtain the label from its corresponding key.
+        This is mostly used when rendering forms with an *initial* value for an
+        AutoCompleteWidget.
+
+
+    .. method:: register(id, queryset, fields[, limit[, key[, label[, auth]]]])
+        
+        This method is used to register a new choices-set with this instance of
+        AutoCompleteView.
+
+        The method accepts as paramter:
+
+         *id*
+            a sequence of letters [#]_ that identifies the choices-set.
+
+         *queryset*
+            the queryset that contains all the possible choices.
+
+            .. note::
+                
+                AutoCompleteView is only able to work with querysets and not with
+                normal *hardcoded* choices, as widgets.Select does.
+
+         *fields*
+            A tuple of field names used to construct the query to get the choices
+            matching the given user input. if ``'__'`` is not present in a field
+            ``'__startswith'`` will be appended to it.
+            
+            ::
+
+                fields = ('username', 'email__exact')
+                # becomes:
+                Q(username__startswith=user_input) | Q(email__exact=user_input)
+
+         *limit*
+            A positive integer used to limit the result of the query.
+
+         *key*
+            A field name, by default ``'pk'``, needed to identify the choices in the
+            queryset. It **must** be an unique field, otherwise more than one choice
+            could have the same key.
+
+         *label*
+            Can be an existing field of the queryset's model or a function that accepts
+            a model as its unique argument and returns a string representation of that
+            model. By default it is::
+                
+                label = lambda obj: smart_unicode(obj)
+
+            .. note::
+                
+                Using a function means that the view will have to get from the db the
+                entire model with all its fields (``SELECT * FROM Model``). Using a
+                field instead will select only the given field.
+
+         *auth*
+            When set to ``True`` only authenticated users will be able to access this
+            choices-set. Defaults to ``False``.
+
+.. data:: autocomplete
+
+    This is the AutoCompleteView used by default. It's an instance of
+    :class:`~autocomplete.views.AutoCompleteView`. If you want to customize
+    your AutoComplete view, you should subclass
+    :class:`autocomplete.views.AutoCompleteView`.
+
+
+Using the autocomplete view in your URLConf
+-------------------------------------------
+
+Here's an example of how to edit
+your URLConf to use the default AutoCompleteView's instance::
+
+    # your project's urls.py
+    from django.conf.urls.defaults import *
+    from autocomplete.views import autocomplete
+
+    urlpatterns = patterns('',
+        # your other urls here.
+        url(r'^autocomplete/(\w+)/$', autocomplete),
+    )
+
+Customizing the AutoCompleteView
+--------------------------------
+
+The methods that can be overidden
+are ``not_found`` and ``forbidden``. They are called respectively when the requested
+choices-set does not exist and when the request is not allowed to access the
+choices-set. Both these methods should return a HttpResponse object.
+
+::
+
+    from django.http import HttpResponse
+    from autocomplete.views import AutoCompleteView
+
+    class MyACView(AutoCompleteView):
+
+        def not_found(self, request, ac_name):
+            content = "choices-set %s, not found" % (ac_name,)
+            return HttpResponse(content, status=404)
+
+        def forbidden(self, request, ac_name):
+            content = "login to access this choices-set"
+            return HttpResponse(content, status=403)
+
+    myacview = MyACView()
+
+You URLConf becomes::
+
+    # your project's urls.py
+    from django.conf.urls.defaults import *
+    
+    from myapp.views import myacview
+
+    urlpatterns = patterns('',
+        # your other urls here.
+        url(r'^autocomplete/(\w+)/$', myappview),
+    )
+
+
+.. note::
+
+    Remember that if you use a custom view you have to explicitly pass it to
+    your AutoCompleteWidget(s) and ModelChoiceField(s) through the ``view``
+    argument.
+
+
+.. rubric:: Footnotes
+
+.. [#] By default everytime the user types a character a call is made. See your
+       Javascript toolkit's Documentation if you want to change this behaviour.
+
+.. [#] You can use any characters you want until they match the autocomplete
+       view's regexp in your URLConf.
+

File docs/library/widgets.rst

+:mod:`autocomplete.widgets` AutoCompleteWidget
+==============================================
+
+.. module:: autocomplete.widgets
+
+.. class:: AutoCompleteWidget(ac_name[, force_selection[, reverse_label[, view[, attrs]]]])
+
+    Just as a Select widget an
+    :class:`AutoCompleteWidget` lets the user select a *choice*
+    from a dropdown box but
+    Instead of displaying all the choices at once, the
+    :class:`AutoCompleteWidget` requires
+    the user to start typing some characters and then gathers, using javascript,
+    the choices matching the user input from a remote :class:`~autocomplete.views.AutoCompleteView`.
+    
+    Performing smaller queries, instead of a single enormous one to get all the
+    choices at once, significantly reduces the load of the database. Moreover
+    it makes easier to select the right choice, because the user has not to search
+    among a big number of options like it could happen with a Select widget.
+
+    To make an :class:`AutoCompleteWidget` work you need to:
+     * serve the javascript that will render the choices to the user;
+     * add an :class:`~autocomplete.views.AutoCompleteView` to your URLConf so
+       the javascript can collect the choices to display;
+     * define one or more *choices-sets* for the
+       :class:`~autocomplete.views.AutoCompleteView` to render.
+
+    .. note::
+        
+        To handle relationships between models use
+        :class:`autocomplete.fields.ModelChoiceField`.
+        It is just like a normal ModelChoiceField but uses an
+        :class:`AutoCompleteWidget` (by default) to render its choices.
+
+
+    .. data:: AC_TEMPLATE
+
+        A string representing the template that
+        :class:`AutoCompleteWidget` uses to render itself as html.
+        It will be formatted with a dict containing the following
+        keys: ``name``, ``hidden_value``, ``value``, ``url`` and ``force_selection``.
+
+
+    .. method:: __init__(ac_name[, force_selection[, reverse_label[, view[, attrs]]]])
+        
+        *ac_name*
+            The name of the choices-set to use with this instance of
+            :class:`AutoCompleteWidget`.
+
+        *force_selection*
+            If is set to True forces the user to select a valid choice. If left
+            to False lets the user write anything in the input.
+            When using :class:`~autocomplete.fields.ModelChoiceField` it is
+            automatically set to True, to ensure a valid model is selected.
+            You should set it to False when you want to provide suggestions to
+            the user.
+
+        *reverse_label*
+            Whether to obtain the label of a choice from its key when rendering
+            the widget with an initial value, or not. This is always set to
+            True by default.
+
+        *view*
+            The view used to retrieve the choices, defaults to
+            :obj:`autocomplete.views.autocomplete`.
+
+        *attrs*
+            A set of html attributes to insert in the autocomplete
+            input field, to customize it (e.g. to add css classes).
+
+
+    .. method:: render(name, value[, attrs])
+        
+        Method used to render the widget as html.
+
+        If the Form is being edited *value* is set to the key of one of the
+        choices (and will be reversed if reverse_label is True), otherwise it
+        is set to None.
+
+        *attrs*
+            A set of html attributes to insert in the autocomplete
+            input field, to customize it (e.g. to add css classes).
+
+
+.. data:: AC_TEMPLATE
+
+    The default template used by
+    :class:`AutoCompleteWidget` to
+    render itself.
+
+
+.. _media-files-configuration:
+
+Configuring the Media files of :class:`AutoCompleteWidget`
+----------------------------------------------------------
+
+By default the :class:`AutoCompleteWidget` uses YUI served from http://yahooapis.com in
+conjunction with the ``js/yui_autocomplete.js`` provided in this package. This
+to not include directly YUI in Django AutoComplete, and to provide a quickly working
+setup. This solution, assuming you are serving ``js/yui_autocomplete.js`` from
+your ``MEDIA_URL``, should work in every situation, including the admin
+application. However in some cases you could need to customize the Media files
+of the widget. For example, if you are already using YUI in your template and
+you don't want it to be included twice, or if you wish to use JQuery or any
+other javascript toolkit [1]_.
+
+::
+
+    AutoCompleteWidget(your_params)
+    # uses YUI loaded from http://yahooapis.com and js/yui_autocomplete.js
+
+    class CustomYUIACWidget(AutoCompleteWidget):
+        """
+        This widget uses your version of YUI served directly from your
+        MEDIA_URL.
+        """
+        class Media:
+            extend = False
+            js = ('js/path/to/yui.js',
+                  # ...
+                  # ...
+                  'js/yui_autocomplete.js')
+
+
+    class CustomJQueryACWidget(AutoCompleteWidget):
+        """
+        This widget uses JQuery served from MEDIA_URL.
+        """
+        class Media:
+            extend = False
+            css = {'all': ('js/thickbox.css',)}
+            js = ('js/jquery.min.js',
+                'js/jquery.bigframe.min.js',
+                'js/jquery.ajaxQueue.js',
+                'js/thickbox-compressed.js',
+                'js/jquery.autocomplete.min.js',
+                'js/jquery_autocomplete.js')
+
+
+    class AnyOtherToolkitACWidget(AutoCompleteWidget):
+        class Media:
+            extend = False
+            js = ('js/path/to/your/toolkit.js',
+                  # ...
+                  # ...
+                  'yourtoolkit_autocomplete.js')
+
+.. note::
+
+    Remember to set ``extend = False`` in your subclass' Media, otherwise your
+    files will be *added* to the default ones instead of replacing them.
+
+.. seealso::
+    
+    `Static Files <http://docs.djangoproject.com/en/dev/howto/static-files/>`_
+        How to correctly serve static files.
+
+    `Form Media <http://docs.djangoproject.com/en/dev/topics/forms/media/>`_
+        How to customize the CSS and Javascript resources of a Form.
+
+
+.. rubric:: Footnotes
+
+.. [1] Currently this package provides only ``yui_autocomplete.js`` and 
+       ``jquery_autocomplete.js``. If you want to use an other toolkit you will
+       have to make the script yourself.
+

File docs/make.bat

+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+set SPHINXBUILD=sphinx-build
+set ALLSPHINXOPTS=-d _build/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html      to make standalone HTML files
+	echo.  dirhtml   to make HTML files named index.html in directories
+	echo.  pickle    to make pickle files
+	echo.  json      to make JSON files
+	echo.  htmlhelp  to make HTML files and a HTML help project
+	echo.  qthelp    to make HTML files and a qthelp project
+	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  changes   to make an overview over all changed/added/deprecated items
+	echo.  linkcheck to check all external links for integrity
+	echo.  doctest   to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (_build\*) do rmdir /q /s %%i
+	del /q /s _build\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% _build/html
+	echo.
+	echo.Build finished. The HTML pages are in _build/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% _build/dirhtml
+	echo.
+	echo.Build finished. The HTML pages are in _build/dirhtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% _build/pickle
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% _build/json
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% _build/htmlhelp
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in _build/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% _build/qthelp
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in _build/qthelp, like this:
+	echo.^> qcollectiongenerator _build\qthelp\django-autocomplete.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile _build\qthelp\django-autocomplete.ghc
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% _build/latex
+	echo.
+	echo.Build finished; the LaTeX files are in _build/latex.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% _build/changes
+	echo.
+	echo.The overview file is in _build/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% _build/linkcheck
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in _build/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% _build/doctest
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in _build/doctest/output.txt.
+	goto end
+)
+
+:end