From 4b451daf1c9a4496cd7c844afae283bbdd41ac7d Mon Sep 17 00:00:00 2001
From: Zygmunt Krynicki <zygmunt.krynicki@linaro.org>
Date: Tue, 14 Jun 2011 13:33:14 +0200
Subject: [PATCH] Revive documentation.

Documentation is now buildable with setup.py build_sphinx.
Some missing components were added to make it consistent and pretty.
---
 MANIFEST.in                     |   7 +-
 doc/changes.rst                 |  49 ++++++++
 doc/conf.py                     | 201 ++++++++++++++++++++++++++++++++
 doc/index.rst                   |  31 +++++
 doc/installation.rst            |  62 ++++++++++
 docs/usage.txt => doc/usage.rst |  71 ++++++-----
 docs/index.txt                  |  13 ---
 docs/install.txt                |  40 -------
 8 files changed, 386 insertions(+), 88 deletions(-)
 create mode 100644 doc/changes.rst
 create mode 100644 doc/conf.py
 create mode 100644 doc/index.rst
 create mode 100644 doc/installation.rst
 rename docs/usage.txt => doc/usage.rst (72%)
 delete mode 100644 docs/index.txt
 delete mode 100644 docs/install.txt

diff --git a/MANIFEST.in b/MANIFEST.in
index ff6e35d..4781fc7 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,5 +1,6 @@
-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
diff --git a/doc/changes.rst b/doc/changes.rst
new file mode 100644
index 0000000..5526812
--- /dev/null
+++ b/doc/changes.rst
@@ -0,0 +1,49 @@
+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.
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..39a80cb
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,201 @@
+# -*- 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}
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..fec8b65
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,31 @@
+======================================
+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`
+
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 0000000..8d60191
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,62 @@
+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.
diff --git a/docs/usage.txt b/doc/usage.rst
similarity index 72%
rename from docs/usage.txt
rename to doc/usage.rst
index 756787d..d875137 100644
--- a/docs/usage.txt
+++ b/doc/usage.rst
@@ -1,5 +1,10 @@
+.. _usage:
+
+Usage
+*****
+
 How to use linaro-django-pagination
-----------------------------
+===================================
 
 ``linaro-django-pagination`` allows for easy Digg-style pagination without modifying
 your views.
@@ -70,42 +75,44 @@ 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::
+In order to override the default pagination template use the extended form of
+the ``paginate`` tag::
 
-    {% with 'pagination/blog/post.html' as pagination_template %}
-        {% autopaginate posts pagesize %}
-        {% paginate %}
-    {% endwith %}
+    {% autopaginate posts pagesize %}
+    {% paginate using "pagination/blog/post.html" %}
 
-The default pagination template is contained in the ``pagination/default.html`` 
-file inside the distribution.
+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.
+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:
+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).
+    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,
@@ -116,21 +123,21 @@ pagination tags.  Here's an overview:
 ``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.
+    does the latter. Defaults to False
 
-``DISPLAY_PAGE_LINKS``
-    If set to ``False``, links for single pages will not be displayed.
+``PAGINATION_DISPLAY_PAGE_LINKS``
+    If set to ``False``, links for single pages will not be displayed. Defaults to True.
 
-``PREVIOUS_LINK_DECORATOR``
-    An HTML prefix for the previous page link; the default value is ``&lsaquo;&lsaquo; ``.
+``PAGINATION_PREVIOUS_LINK_DECORATOR``
+    An HTML prefix for the previous page link; the default value is ``&lsaquo;&lsaquo;``.
 
-``NEXT_LINK_DECORATOR``
-    An HTML postfix for the next page link; the default value is `` &rsaquo;&rsaquo;``.
+``PAGINATION_NEXT_LINK_DECORATOR``
+    An HTML postfix for the next page link; the default value is ``&rsaquo;&rsaquo;``.
 
-``DISPLAY_DISABLED_PREVIOUS_LINK``
+``PAGINATION_DISPLAY_DISABLED_PREVIOUS_LINK``
     If set to ``False``, the previous page link will not be displayed if there's 
-    no previous page.
+    no previous page. Defaults to False.
 
-``DISPLAY_DISABLED_NEXT_LINK``
+``PAGINATION_DISPLAY_DISABLED_NEXT_LINK``
     If set to ``False``, the next page link will not be displayed if there's no 
-    next page.
+    next page. Defaults to False.
diff --git a/docs/index.txt b/docs/index.txt
deleted file mode 100644
index b9dbafe..0000000
--- a/docs/index.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-#################
-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
diff --git a/docs/install.txt b/docs/install.txt
deleted file mode 100644
index f70d4d3..0000000
--- a/docs/install.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-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
-- 
2.20.1