Documentation is now buildable with setup.py build_sphinx.
Some missing components were added to make it consistent and pretty.
-include COPYING
include CONTRIBUTORS.txt
-recursive-include docs *
-recursive-include linaro_django_pagination/templates/pagination *.html
+include COPYING
+include doc/conf.py
+recursive-include doc *.rst
recursive-include linaro_django_pagination/locale *.po
+recursive-include linaro_django_pagination/templates/pagination *.html
--- /dev/null
+Version History
+***************
+
+.. _version_2_0:
+
+Version 2.0
+===========
+
+
+* Revived the project as a fork of
+ git://github.com/ericflo/django-pagination.git. The project now has a new
+ maintainer (Zygmunt Krynicki) and a new home (on pypi and launchpad).
+
+* Merged a lot of branches of the old project. In general this was made to show
+ people "here is the new good stuff" and to get as much contributions, back
+ into the trunk, as possible.
+
+* Merge a lot of translations: de, es, fr, it, nn, no, pl, pt, pt_BR, ru and
+ tr. Translations are still in a bad state (they are not built automatically,
+ they are in incorrect place) but the first step is done.
+
+* Add support for custom pagination templates. You can now use the optional
+ argument on paginate to use different template::
+
+ {% autopaginate obj_list %}
+ ...
+ {% paginate using "something/custom_template.html" %}
+
+* Pagination template has support for specific blocks. Those blocks are
+ 'previouslink', 'pagelinks' and 'nextlink'. Make sure to base your template
+ on pagination/pagination.html end extend the blocks you care about.
+
+* Add support for using multiple paginations on a single page. Simply use
+ multiple autopaginate/paginate tags. The only limitation is that you must use
+ paginate before using the next autopaginate tag. For an example see the test
+ project and the example application inside.
+
+* Simplify building documentation. To build the documentation simply run
+ `setup.py build_sphinx`. You will need sphinx installed obviously.
+
+* Simplify running tests. To run tests just invoke `setup.py test`. That's all!
+ This is based on the goodness of django-testproject that simplifies setting
+ up helper projects just for testing.
+
+
+Version 1.0.7
+=============
+
+* Last release from previous upstream developer.
--- /dev/null
+# -*- coding: utf-8 -*-
+#
+# Linaro JSON documentation build configuration file, created by
+# sphinx-quickstart on Mon Dec 27 16:39:47 2010.
+#
+# 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
+import 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', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = []
+
+# 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'Linaro Django Pagination'
+copyright = u'2010-2011, Linaro Limited'
+
+# 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.
+import versiontools
+import linaro_django_pagination
+version = "%d.%d" % linaro_django_pagination.__version__[0:2]
+# The full version, including alpha/beta/rc tags.
+release = versiontools.format_version(linaro_django_pagination.__version__)
+
+# 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 = []
+
+# 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 = []
+
+# 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 = 'LinaroDjangoPaginationDocumentation'
+
+
+# -- 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', 'LinaroDjangoPagination.tex', u'Linaro Django Pagination Documentation',
+ u'Zygmunt Krynicki', '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
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
--- /dev/null
+======================================
+Linaro Django Pagination Documentation
+======================================
+
+.. automodule:: linaro_django_pagination
+
+.. seealso:: To get started quickly see :ref:`usage`
+.. seealso:: See what's new in :ref:`version_2_0`
+
+Features
+========
+
+* Quickly create nice-looking paginated lists without altering your views
+* Support for multiple lists per page
+* Support for using custom templates for each pagination
+
+
+Indices and tables
+==================
+
+.. toctree::
+ :maxdepth: 2
+
+ installation.rst
+ usage.rst
+ changes.rst
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
--- /dev/null
+Installation
+============
+
+Prerequisites
+^^^^^^^^^^^^^
+
+This package requires django 1.2. It is not tested on earlier versions and may
+not work properly there.
+
+To build the documentation from source you will need sphinx.
+
+Installation Options
+^^^^^^^^^^^^^^^^^^^^
+
+There are several installation options available:
+
+Using Ubuntu PPAs
+-----------------
+
+For Ubuntu 10.04 onward there is a stable PPA (personal package archive):
+
+* ppa:linaro-validation/ppa
+
+To add a ppa to an Ubuntu system use the add-apt-repository command::
+
+ sudo add-apt-repository ppa:linaro-validation/ppa
+
+After you add the PPA you need to update your package cache::
+
+ sudo apt-get update
+
+Finally you can install the package, it is called `python-versiontools`::
+
+ sudo apt-get install python-linaro-django-pagination
+
+
+Using Python Package Index
+--------------------------
+
+This package is being actively maintained and published in the `Python Package
+Index <http://http://pypi.python.org>`_. You can install it if you have `pip
+<http://pip.openplans.org/>`_ tool using just one line::
+
+ pip install linaro-django-pagination
+
+
+Using source tarball
+--------------------
+
+To install from source you must first obtain a source tarball from either pypi
+or from `Launchpad <http://launchpad.net/>`_. To install the package unpack the
+tarball and run::
+
+ python setup.py install
+
+You can pass ``--user`` if you prefer to do a local (non system-wide) installation.
+
+.. note::
+
+ To install from source you will need distutils (replacement of setuptools)
+ They are typically installed on any Linux system with python but on Windows
+ you may need to install that separately.
--- /dev/null
+.. _usage:
+
+Usage
+*****
+
+How to use linaro-django-pagination
+===================================
+
+``linaro-django-pagination`` allows for easy Digg-style pagination without modifying
+your views.
+
+There are really 5 steps to setting it up with your projects (not including
+installation, which is covered in INSTALL.txt in this same directory.)
+
+1. List this application in the ``INSTALLED_APPS`` portion of your settings
+ file. Your settings file might look something like::
+
+ INSTALLED_APPS = (
+ # ...
+ 'pagination',
+ )
+
+
+2. Install the pagination middleware. Your settings file might look something
+ like::
+
+ MIDDLEWARE_CLASSES = (
+ # ...
+ 'pagination.middleware.PaginationMiddleware',
+ )
+
+3. If it's not already added in your setup, add the request context processor.
+ Note that context processors are set by default implicitly, so to set them
+ explicitly, you need to copy and paste this code into your under
+ the value TEMPLATE_CONTEXT_PROCESSORS::
+
+ ("django.core.context_processors.auth",
+ "django.core.context_processors.debug",
+ "django.core.context_processors.i18n",
+ "django.core.context_processors.media",
+ "django.core.context_processors.request")
+
+4. Add this line at the top of your template to load the pagination tags:
+
+ {% load pagination_tags %}
+
+
+5. Decide on a variable that you would like to paginate, and use the
+ autopaginate tag on that variable before iterating over it. This could
+ take one of two forms (using the canonical ``object_list`` as an example
+ variable):
+
+ {% autopaginate object_list %}
+
+ This assumes that you would like to have the default 20 results per page.
+ If you would like to specify your own amount of results per page, you can
+ specify that like so:
+
+ {% autopaginate object_list 10 %}
+
+ Note that this replaces ``object_list`` with the list for the current page, so
+ you can iterate over the ``object_list`` like you normally would.
+
+
+6. Now you want to display the current page and the available pages, so
+ somewhere after having used autopaginate, use the paginate inclusion tag:
+
+ {% paginate %}
+
+ This does not take any arguments, but does assume that you have already
+ called autopaginate, so make sure to do so first.
+
+
+That's it! You have now paginated ``object_list`` and given users of the site
+a way to navigate between the different pages--all without touching your views.
+
+Custom pagination templates
+===========================
+
+In order to override the default pagination template use the extended form of
+the ``paginate`` tag::
+
+ {% autopaginate posts pagesize %}
+ {% paginate using "pagination/blog/post.html" %}
+
+The default pagination template is contained in the
+``pagination/pagination.html`` file inside the distribution.
+
+A Note About Uploads
+====================
+
+It is important, when using linaro-django-pagination in conjunction with file
+uploads, to be aware of when ``request.page`` is accessed. As soon as
+``request.page`` is accessed, ``request.upload_handlers`` is frozen and cannot
+be altered in any way. It's a good idea to access the ``page`` attribute on
+the request object as late as possible in your views.
+
+
+Optional Settings
+=================
+
+In linaro-django-pagination, there are no required settings. There are,
+however, a small set of optional settings useful for changing the default
+behavior of the pagination tags. Here's an overview:
+
+``PAGINATION_DEFAULT_PAGINATION``
+ The default amount of items to show on a page if no number is specified.
+ Defaults to 20
+
+``PAGINATION_DEFAULT_WINDOW``
+ The number of items to the left and to the right of the current page to
+ display (accounting for ellipses). Defaults to 4.
+
+``PAGINATION_DEFAULT_MARGIN``
+ FIXME: This needs to be documented.
+
+``PAGINATION_DEFAULT_ORPHANS``
+ The number of orphans allowed. According to the Django documentation,
+ orphans are defined as::
+
+ The minimum number of items allowed on the last page, defaults to zero.
+
+``PAGINATION_INVALID_PAGE_RAISES_404``
+ Determines whether an invalid page raises an ``Http404`` or just sets the
+ ``invalid_page`` context variable. ``True`` does the former and ``False``
+ does the latter. Defaults to False
+
+``PAGINATION_DISPLAY_PAGE_LINKS``
+ If set to ``False``, links for single pages will not be displayed. Defaults to True.
+
+``PAGINATION_PREVIOUS_LINK_DECORATOR``
+ An HTML prefix for the previous page link; the default value is ``‹‹``.
+
+``PAGINATION_NEXT_LINK_DECORATOR``
+ An HTML postfix for the next page link; the default value is ``››``.
+
+``PAGINATION_DISPLAY_DISABLED_PREVIOUS_LINK``
+ If set to ``False``, the previous page link will not be displayed if there's
+ no previous page. Defaults to False.
+
+``PAGINATION_DISPLAY_DISABLED_NEXT_LINK``
+ If set to ``False``, the next page link will not be displayed if there's no
+ next page. Defaults to False.
+++ /dev/null
-#################
-linaro-django-pagination
-#################
-
-Django-pagination is a set of utilities for creating robust pagination tools
-throughout a django application.
-
-Contents:
-
-.. toctree::
-
- install.txt
- usage.txt
\ No newline at end of file
+++ /dev/null
-Installing the latest development version of linaro-linaro-django-pagination
----------------------------------------------------------------
-
-To install, first check out the latest version of the application from
-subversion:
-
- svn co http://linaro-django-pagination.googlecode.com/svn/trunk linaro-django-pagination
-
-Now, link the inner ``pagination`` project to your Python path:
-
- sudo ln -s `pwd`/pagination SITE_PACKAGES_DIR/pagination
-
-If you don't know the location of your site packages directory, this hack might
-do the trick for you:
-
- sudo ln -s `pwd`/pagination `python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"`/pagination
-
-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 linaro-django-pagination at will.
-
-Installing via setuptools
--------------------------
-
-If you have setuptools_ installed, you can simply run the following command
-to install linaro-django-pagination:
-
- sudo easy_install linaro-django-pagination
-
-.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+++ /dev/null
-How to use linaro-django-pagination
-----------------------------
-
-``linaro-django-pagination`` allows for easy Digg-style pagination without modifying
-your views.
-
-There are really 5 steps to setting it up with your projects (not including
-installation, which is covered in INSTALL.txt in this same directory.)
-
-1. List this application in the ``INSTALLED_APPS`` portion of your settings
- file. Your settings file might look something like::
-
- INSTALLED_APPS = (
- # ...
- 'pagination',
- )
-
-
-2. Install the pagination middleware. Your settings file might look something
- like::
-
- MIDDLEWARE_CLASSES = (
- # ...
- 'pagination.middleware.PaginationMiddleware',
- )
-
-3. If it's not already added in your setup, add the request context processor.
- Note that context processors are set by default implicitly, so to set them
- explicitly, you need to copy and paste this code into your under
- the value TEMPLATE_CONTEXT_PROCESSORS::
-
- ("django.core.context_processors.auth",
- "django.core.context_processors.debug",
- "django.core.context_processors.i18n",
- "django.core.context_processors.media",
- "django.core.context_processors.request")
-
-4. Add this line at the top of your template to load the pagination tags:
-
- {% load pagination_tags %}
-
-
-5. Decide on a variable that you would like to paginate, and use the
- autopaginate tag on that variable before iterating over it. This could
- take one of two forms (using the canonical ``object_list`` as an example
- variable):
-
- {% autopaginate object_list %}
-
- This assumes that you would like to have the default 20 results per page.
- If you would like to specify your own amount of results per page, you can
- specify that like so:
-
- {% autopaginate object_list 10 %}
-
- Note that this replaces ``object_list`` with the list for the current page, so
- you can iterate over the ``object_list`` like you normally would.
-
-
-6. Now you want to display the current page and the available pages, so
- somewhere after having used autopaginate, use the paginate inclusion tag:
-
- {% paginate %}
-
- This does not take any arguments, but does assume that you have already
- called autopaginate, so make sure to do so first.
-
-
-That's it! You have now paginated ``object_list`` and given users of the site
-a way to navigate between the different pages--all without touching your views.
-
-Custom pagination templates
----------------------------
-
-In order to override the default pagination template, declare a context variable
-named ``pagination_template`` set to the template name::
-
- {% with 'pagination/blog/post.html' as pagination_template %}
- {% autopaginate posts pagesize %}
- {% paginate %}
- {% endwith %}
-
-The default pagination template is contained in the ``pagination/default.html``
-file inside the distribution.
-
-A Note About Uploads
---------------------
-
-It is important, when using linaro-django-pagination in conjunction with file uploads,
-to be aware of when ``request.page`` is accessed. As soon as ``request.page``
-is accessed, ``request.upload_handlers`` is frozen and cannot be altered in any
-way. It's a good idea to access the ``page`` attribute on the request object
-as late as possible in your views.
-
-
-Optional Settings
-------------------
-
-In linaro-django-pagination, there are no required settings. There are, however, a
-small set of optional settings useful for changing the default behavior of the
-pagination tags. Here's an overview:
-
-``PAGINATION_DEFAULT_PAGINATION``
- The default amount of items to show on a page if no number is specified.
-
-``PAGINATION_DEFAULT_WINDOW``
- The number of items to the left and to the right of the current page to
- display (accounting for ellipses).
-
-``PAGINATION_DEFAULT_ORPHANS``
- The number of orphans allowed. According to the Django documentation,
- orphans are defined as::
-
- The minimum number of items allowed on the last page, defaults to zero.
-
-``PAGINATION_INVALID_PAGE_RAISES_404``
- Determines whether an invalid page raises an ``Http404`` or just sets the
- ``invalid_page`` context variable. ``True`` does the former and ``False``
- does the latter.
-
-``DISPLAY_PAGE_LINKS``
- If set to ``False``, links for single pages will not be displayed.
-
-``PREVIOUS_LINK_DECORATOR``
- An HTML prefix for the previous page link; the default value is ``‹‹ ``.
-
-``NEXT_LINK_DECORATOR``
- An HTML postfix for the next page link; the default value is `` ››``.
-
-``DISPLAY_DISABLED_PREVIOUS_LINK``
- If set to ``False``, the previous page link will not be displayed if there's
- no previous page.
-
-``DISPLAY_DISABLED_NEXT_LINK``
- If set to ``False``, the next page link will not be displayed if there's no
- next page.
fnp / django-pagination.git / commitdiff