diff --git a/avatar/api/docs/Makefile b/avatar/api/docs/Makefile deleted file mode 100644 index d4bb2cb..0000000 --- a/avatar/api/docs/Makefile +++ /dev/null @@ -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) diff --git a/avatar/api/docs/conf.py b/avatar/api/docs/conf.py deleted file mode 100644 index 743b82a..0000000 --- a/avatar/api/docs/conf.py +++ /dev/null @@ -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" diff --git a/avatar/api/docs/make.bat b/avatar/api/docs/make.bat deleted file mode 100644 index 954237b..0000000 --- a/avatar/api/docs/make.bat +++ /dev/null @@ -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 diff --git a/avatar/api/docs/avatar.rst b/docs/avatar.rst similarity index 100% rename from avatar/api/docs/avatar.rst rename to docs/avatar.rst diff --git a/avatar/api/docs/index.rst b/docs/index.rst similarity index 99% rename from avatar/api/docs/index.rst rename to docs/index.rst index e28688c..bf7a740 100644 --- a/avatar/api/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/index.txt b/docs/index.txt deleted file mode 100644 index 3de6484..0000000 --- a/docs/index.txt +++ /dev/null @@ -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:: - - Change your avatar - -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 `_. 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 - `_. 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 `_. - 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/