From 58b7fe59b2c92cf5bfd6225a520c54677d76a85c Mon Sep 17 00:00:00 2001 From: Eric Florenzano Date: Tue, 28 Oct 2008 09:44:53 +0000 Subject: [PATCH] Added inital pass of documentation. git-svn-id: http://django-avatar.googlecode.com/svn/trunk@33 c76b2324-5f53-0410-85ac-b1078a54aeeb --- CONTRIBUTORS.txt | 2 +- INSTALL.txt | 1 - README.txt | 1 - avatar/management/commands/rebuild_avatars.py | 6 +- docs/index.txt | 15 ++ docs/install.txt | 40 +++++ docs/usage.txt | 138 ++++++++++++++++++ 7 files changed, 197 insertions(+), 6 deletions(-) delete mode 100644 INSTALL.txt delete mode 100644 README.txt create mode 100644 docs/index.txt create mode 100644 docs/install.txt create mode 100644 docs/usage.txt diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt index 8b13789..05b56ac 100644 --- a/CONTRIBUTORS.txt +++ b/CONTRIBUTORS.txt @@ -1 +1 @@ - +This application is mainly developed by Eric Florenzano. diff --git a/INSTALL.txt b/INSTALL.txt deleted file mode 100644 index 8b13789..0000000 --- a/INSTALL.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/README.txt b/README.txt deleted file mode 100644 index 8b13789..0000000 --- a/README.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/avatar/management/commands/rebuild_avatars.py b/avatar/management/commands/rebuild_avatars.py index a58173b..28b64ad 100644 --- a/avatar/management/commands/rebuild_avatars.py +++ b/avatar/management/commands/rebuild_avatars.py @@ -2,11 +2,11 @@ from django.core.management.base import NoArgsCommand from django.conf import settings from avatar.models import Avatar - -AUTO_GENERATE_AVATAR_SIZES = getattr(settings, 'AUTO_GENERATE_AVATAR_SIZES', (80,)) +from avatar import AUTO_GENERATE_AVATAR_SIZES class Command(NoArgsCommand): - help = "Import avatars from Gravatar, and store them locally." + help = "Regenerates avatar thumbnails for the sizes specified in " + \ + "settings.AUTO_GENERATE_AVATAR_SIZES." def handle_noargs(self, **options): for avatar in Avatar.objects.all(): diff --git a/docs/index.txt b/docs/index.txt new file mode 100644 index 0000000..7019aa6 --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,15 @@ +############# +django-avatar +############# + +Django-avatar is a reusable application for handling user avatars. It has the +ability to default to Gravatar_ if no avatar is found for a certain user. +Django-avatar automatically generates thumbnails and stores them to your default +file storage backend for retrieval later. + +Contents: + +.. toctree:: + + install.txt + usage.txt \ No newline at end of file diff --git a/docs/install.txt b/docs/install.txt new file mode 100644 index 0000000..1c69627 --- /dev/null +++ b/docs/install.txt @@ -0,0 +1,40 @@ +Installing the latest development version of django-avatar +---------------------------------------------------------- + +To install, first check out the latest version of the application from +subversion: + + svn co http://django-avatar.googlecode.com/svn/trunk django-avatar + +Now, link the inner ``avatar`` project to your Python path: + + sudo ln -s `pwd`/avatar SITE_PACKAGES_DIR/avatar + +If you don't know the location of your site packages directory, this hack might +do the trick for you: + + sudo ln -s `pwd`/avatar `python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"`/avatar + +Now it's installed! Please see usage.txt for information on how to use this +application in your projects. + +Installing via setup.py +----------------------- + +Included with this application is a file named ``setup.py``. It's possible to +use this file to install this application to your system, by invoking the +following command: + + sudo python setup.py install + +Once that's done, you should be able to begin using django-avatar at will. + +Installing via setuptools +------------------------- + +If you have setuptools_ installed, you can simply run the following command +to install django-avatar: + + sudo easy_install django-avatar + +.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools \ No newline at end of file diff --git a/docs/usage.txt b/docs/usage.txt new file mode 100644 index 0000000..73785c6 --- /dev/null +++ b/docs/usage.txt @@ -0,0 +1,138 @@ +Using django-avatar +=================== + + +Basics +------ + +To integrate ``django-avatar`` with your site, there are relatively few things +that are required. A minimal integration can work like this: + +1. List this application in the ``INSTALLED_APPS`` portion of your settings + file. Your settings file will look something like:: + + INSTALLED_APPS = ( + # ... + 'avatar', + ) + +2. Add the pagination urls to the end of your root urlconf. Your urlconf + will look something like:: + + urlpatterns = patterns('', + # ... + (r'^admin/(.*)', admin.site.root), + (r'^avatar/', include('avatar.urls')), + ) + +3. Somewhere in your template navigation scheme, link to the change avatar + page:: + + Change your avatar + +4. Wherever you want to display an avatar for a user, first load the avatar + template tags:: + + {% load avatar_tags %} + + Then, use the ``avatar`` tag to display an avatar of a default size:: + + {% avatar user %} + + Or specify a size (in pixels) explicitly:: + + {% avatar user 65 %} + +5. Optionally customize ``avatar/change.html`` and + ``avatar/confirm_delete.html`` to conform to your site's look and feel. + + +Views +----- + +There are only two views for this application: one for changing a user's avatar, +and another for deleting a user's avatar. + +Changing an avatar +~~~~~~~~~~~~~~~~~~ + +The actual view function is located at ``avatar.views.change``, and this can +be referenced by the url name ``avatar_change``. It takes two keyword +arguments: ``extra_context`` and ``next_override``. If ``extra_context`` is +provided, that context will be placed into the template's context. + +If ``next_override`` is provided, the user will be redirected to the specified +URL after form submission. Otherwise the user will be redirected to the URL +specified in the ``next`` parameter in ``request.POST``. If ``request.POST`` +has no ``next`` parameter, ``request.GET`` will be searched. If ``request.GET`` +has no ``next`` parameter, the ``HTTP_REFERER`` header will be inspected. If +that header does not exist, the user will be redirected back to the current URL. + +Deleting an avatar +~~~~~~~~~~~~~~~~~~ + +The actual view function is located at ``avatar.views.delete``, and this can be +referenced by the url name ``avatar_delete``. It takes the same two keyword +arguments as ``avatar.views.change`` and follows the same redirection rules +as well. + + +Template Tags +------------- + +To begin using these template tags, you must first load the tags into the +template rendering system: + + {% load avatar_tags %} + +``{% avatar_url user [size in pixels] %}`` + Renders the URL of the avatar for the given user. User can be either a + ``django.contrib.auth.models.User`` object instance or a username. + +``{% avatar user [size in pixels] %}`` + Renders an HTML ``img`` tag for the given user for the specified size. User + can be either a ``django.contrib.auth.models.User`` object instance or a + username. + +``{% render_avatar avatar [size in pixels] %}`` + Given an actual ``avatar.models.Avatar`` object instance, renders an HTML + ``img`` tag to represent that avatar at the requested size. + + +Global Settings +--------------- + +There are a number of settings available to easily customize the avatars that +appear on the site. Listed below are those settings: + +AUTO_GENERATE_AVATAR_SIZES + An iterable of integers representing the sizes of avatars to generate on + upload. This can save rendering time later on if you pre-generate the + resized versions. Defaults to ``(80,)`` + +AVATAR_RESIZE_METHOD + The method to use when resizing images, based on the options available in + PIL. Defaults to ``Image.ANTIALIAS``. + +AVATAR_STORAGE_DIR + The directory under ``MEDIA_ROOT`` to store the images. If using a + non-filesystem storage device, this will simply be appended to the beginning + of the file name. + +AVATAR_GRAVATAR_BACKUP + A boolean determining whether to default to the Gravatar service if no + ``Avatar`` instance is found in the system for the given user. Defaults to + True. + +AVATAR_DEFAULT_URL + The default URL to default to if ``AVATAR_GRAVATAR_BACKUP`` is set to False + and there is no ``Avatar`` instance found in the system for the given user. + + +Management Commands +------------------- + +This application does include one management command: ``rebuild_avatars``. It +takes no arguments and, when run, re-renders all of the thumbnails for all of +the avatars for the pixel sizes specified in the ``AUTO_GENERATE_AVATAR_SIZES`` +setting. \ No newline at end of file