mirror of
https://github.com/jazzband/django-avatar.git
synced 2026-03-16 22:20:30 +00:00
unify documentation
This commit is contained in:
Johannes Wilm
parent
37d904c4ad
commit
403a9283b3
6 changed files with 1 additions and 366 deletions
|
|
@ -1,20 +0,0 @@
|
|||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project = "django-avatar"
|
||||
copyright = "2013, django-avatar developers"
|
||||
author = "keyvan"
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions = []
|
||||
|
||||
templates_path = ["_templates"]
|
||||
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
||||
|
||||
htmlhelp_basename = "django-avatar apidoc"
|
||||
|
||||
source_suffix = ".rst"
|
||||
|
||||
master_doc = "index"
|
||||
pygments_style = "sphinx"
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_static_path = ["_static"]
|
||||
epub_show_urls = "footnote"
|
||||
|
|
@ -1,35 +0,0 @@
|
|||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.https://www.sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
|
|
@ -212,14 +212,13 @@ appear on the site. Listed below are those settings:
|
|||
.. py:data:: AVATAR_RESIZE_METHOD
|
||||
|
||||
The method to use when resizing images, based on the options available in
|
||||
Pillow. Defaults to ``Image.LANCZOS``.
|
||||
Pillow. Defaults to ``Image.Resampling.LANCZOS``.
|
||||
|
||||
.. py:data:: 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. Defaults to ``avatars``.
|
||||
Pillow. Defaults to ``Image.ANTIALIAS``.
|
||||
|
||||
.. py:data:: AVATAR_THUMB_FORMAT
|
||||
|
||||
276
docs/index.txt
276
docs/index.txt
|
|
@ -1,276 +0,0 @@
|
|||
django-avatar
|
||||
=============
|
||||
|
||||
Django-avatar is a reusable application for handling user avatars. It has the
|
||||
ability to default to avatars provided by third party services (like Gravatar_
|
||||
or Facebook) 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.
|
||||
|
||||
.. _Gravatar: https://gravatar.com
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
If you have pip_ installed, you can simply run the following command
|
||||
to install django-avatar::
|
||||
|
||||
pip install django-avatar
|
||||
|
||||
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::
|
||||
|
||||
python setup.py install
|
||||
|
||||
Once that's done, you should be able to begin using django-avatar at will.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
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. Migrate your database::
|
||||
|
||||
python manage.py migrate
|
||||
|
||||
3. Add the avatar urls to the end of your root urlconf. Your urlconf
|
||||
will look something like::
|
||||
|
||||
urlpatterns = [
|
||||
# ...
|
||||
path('avatar/', include('avatar.urls')),
|
||||
]
|
||||
|
||||
4. Somewhere in your template navigation scheme, link to the change avatar
|
||||
page::
|
||||
|
||||
<a href="{% url 'avatar_change' %}">Change your avatar</a>
|
||||
|
||||
5. 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 %}
|
||||
|
||||
Or specify a width and height (in pixels) explicitly::
|
||||
|
||||
{% avatar user 65 50 %}
|
||||
|
||||
Example for customize the attribute of the HTML ``img`` tag::
|
||||
|
||||
{% avatar user 65 class="img-circle img-responsive" id="user_avatar" %}
|
||||
|
||||
Template tags and filter
|
||||
------------------------
|
||||
|
||||
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] **kwargs %}``
|
||||
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. The (key, value) pairs in kwargs will be added to ``img`` tag
|
||||
as its attributes.
|
||||
|
||||
``{% 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.
|
||||
|
||||
``{{ request.user|has_avatar }}``
|
||||
Given a user object returns a boolean if the user has an avatar.
|
||||
|
||||
Global Settings
|
||||
---------------
|
||||
|
||||
There are a number of settings available to easily customize the avatars that
|
||||
appear on the site. Listed below are those settings:
|
||||
|
||||
.. py:data:: AVATAR_AUTO_GENERATE_SIZES
|
||||
|
||||
An iterable of integers and/or sequences in the format ``(width, height)``
|
||||
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,)``.
|
||||
|
||||
.. py:data:: AVATAR_CACHE_ENABLED
|
||||
|
||||
Set to ``False`` if you completely disable avatar caching. Defaults to ``True``.
|
||||
|
||||
.. py:data:: AVATAR_DEFAULT_URL
|
||||
|
||||
The default URL to default to if the
|
||||
:py:class:`~avatar.providers.GravatarAvatarProvider` is not used and there
|
||||
is no ``Avatar`` instance found in the system for the given user.
|
||||
|
||||
.. py:data:: AVATAR_EXPOSE_USERNAMES
|
||||
|
||||
Puts the User's username field in the URL path when ``True``. Set to
|
||||
``False`` to use the User's primary key instead, preventing their email
|
||||
from being searchable on the web. Defaults to ``False``.
|
||||
|
||||
.. py:data:: AVATAR_FACEBOOK_GET_ID
|
||||
|
||||
A callable or string path to a callable that will return the user's
|
||||
Facebook ID. The callable should take a ``User`` object and return a
|
||||
string. If you want to use this then make sure you included
|
||||
:py:class:`~avatar.providers.FacebookAvatarProvider` in :py:data:`AVATAR_PROVIDERS`.
|
||||
|
||||
.. py:data:: AVATAR_GRAVATAR_DEFAULT
|
||||
|
||||
A string determining the default Gravatar. Can be a URL to a custom image
|
||||
or a style of Gravatar. Ex. `retro`. All Available options listed in the
|
||||
`Gravatar documentation <https://en.gravatar.com/site/implement/images
|
||||
/#default-image>`_. Defaults to ``None``.
|
||||
|
||||
.. py:data:: AVATAR_GRAVATAR_FORCEDEFAULT
|
||||
|
||||
A bool indicating whether or not to always use the default Gravitar. More
|
||||
details can be found in the `Gravatar documentation
|
||||
<https://en.gravatar.com/site/implement/images/#force-default>`_. Defaults
|
||||
to ``False``.
|
||||
|
||||
.. py:data:: AVATAR_GRAVATAR_FIELD
|
||||
|
||||
The name of the user's field containing the gravatar email. For example,
|
||||
if you set this to ``gravatar`` then django-avatar will get the user's
|
||||
gravatar in ``user.gravatar``. Defaults to ``email``.
|
||||
|
||||
.. py:data:: AVATAR_MAX_SIZE
|
||||
|
||||
File size limit for avatar upload. Default is ``1024 * 1024`` (1 MB).
|
||||
gravatar in ``user.gravatar``.
|
||||
|
||||
.. py:data:: AVATAR_MAX_AVATARS_PER_USER
|
||||
|
||||
The maximum number of avatars each user can have. Default is ``42``.
|
||||
|
||||
.. py:data:: AVATAR_PATH_HANDLER
|
||||
|
||||
Path to a method for avatar file path handling. Default is
|
||||
``avatar.models.avatar_path_handler``.
|
||||
|
||||
.. py:data:: AVATAR_PROVIDERS
|
||||
|
||||
Tuple of classes that are tried in the given order for returning avatar
|
||||
URLs.
|
||||
Defaults to::
|
||||
|
||||
(
|
||||
'avatar.providers.PrimaryAvatarProvider',
|
||||
'avatar.providers.LibRAvatarProvider',
|
||||
'avatar.providers.GravatarAvatarProvider',
|
||||
'avatar.providers.DefaultAvatarProvider',
|
||||
)
|
||||
|
||||
If you want to implement your own provider, it must provide a class method
|
||||
``get_avatar_url(user, width, height)``.
|
||||
|
||||
.. py:class:: avatar.providers.PrimaryAvatarProvider
|
||||
|
||||
Returns the primary avatar stored for the given user.
|
||||
|
||||
.. py:class:: avatar.providers.GravatarAvatarProvider
|
||||
|
||||
Adds support for the Gravatar service and will always return an avatar
|
||||
URL. If the user has no avatar registered with Gravatar a default will
|
||||
be used (see :py:data:`AVATAR_GRAVATAR_DEFAULT`).
|
||||
|
||||
.. py:class:: avatar.providers.FacebookAvatarProvider
|
||||
|
||||
Add this provider to :py:data:`AVATAR_PROVIDERS` in order to add
|
||||
support for profile images from Facebook. Note that you also need to
|
||||
set the :py:data:`AVATAR_FACEBOOK_GET_ID` setting.
|
||||
|
||||
.. py:class:: avatar.providers.DefaultAvatarProvider
|
||||
|
||||
Provides a fallback avatar defined in :py:data:`AVATAR_DEFAULT_URL`.
|
||||
|
||||
.. py:data:: AVATAR_RESIZE_METHOD
|
||||
|
||||
The method to use when resizing images, based on the options available in
|
||||
Pillow. Defaults to ``Image.Resampling.LANCZOS``.
|
||||
|
||||
.. py:data:: 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. Defaults to ``avatars``.
|
||||
Pillow. Defaults to ``Image.ANTIALIAS``.
|
||||
|
||||
.. py:data:: AVATAR_THUMB_FORMAT
|
||||
|
||||
The file format of thumbnails, based on the options available in
|
||||
Pillow. Defaults to `PNG`.
|
||||
|
||||
.. py:data:: AVATAR_THUMB_QUALITY
|
||||
|
||||
The quality of thumbnails, between 0 (worst) to 95 (best) or the string
|
||||
"keep" (only JPEG) as provided by Pillow. Defaults to `85`.
|
||||
|
||||
.. py:data:: AVATAR_THUMB_MODES
|
||||
|
||||
A sequence of acceptable modes for thumbnails as provided by Pillow. If the mode
|
||||
of the image is not in the list, the thumbnail will be converted to the
|
||||
first mode in the list. Defaults to `('RGB', 'RGBA')`.
|
||||
|
||||
.. py:data:: AVATAR_CLEANUP_DELETED
|
||||
|
||||
``True`` if the avatar image files should be deleted when an avatar is
|
||||
deleted from the database. Defaults to ``True``.
|
||||
|
||||
.. py:data:: AVATAR_ADD_TEMPLATE
|
||||
|
||||
Path to the Django template to use for adding a new avatar. Defaults to
|
||||
``avatar/add.html``.
|
||||
|
||||
.. py:data:: AVATAR_CHANGE_TEMPLATE
|
||||
|
||||
Path to the Django template to use for changing a user's avatar. Defaults to ``avatar/change.html``.
|
||||
|
||||
.. py:data:: AVATAR_DELETE_TEMPLATE
|
||||
|
||||
Path to the Django template to use for confirming a delete of a user's
|
||||
avatar. Defaults to ``avatar/avatar/confirm_delete.html``.
|
||||
|
||||
.. py:data:: AVATAR_ALLOWED_MIMETYPES
|
||||
|
||||
Limit allowed avatar image uploads by their actual content payload and what image codecs we wish to support.
|
||||
This limits website user content site attack vectors against image codec buffer overflow and similar bugs.
|
||||
`You must have python-imaging library installed <https://github.com/ahupp/python-magic>`_.
|
||||
Suggested safe setting: ``("image/png", "image/gif", "image/jpeg")``.
|
||||
When enabled you'll get the following error on the form upload *File content is invalid. Detected: image/tiff Allowed content types are: image/png, image/gif, image/jpg*.
|
||||
|
||||
|
||||
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
|
||||
:py:data:`AVATAR_AUTO_GENERATE_SIZES` setting.
|
||||
|
||||
|
||||
.. _pip: https://www.pip-installer.org/
|
||||
Loading…
Reference in a new issue