Revive documentation.
authorZygmunt Krynicki <zygmunt.krynicki@linaro.org>
Tue, 14 Jun 2011 11:33:14 +0000 (13:33 +0200)
committerZygmunt Krynicki <zygmunt.krynicki@linaro.org>
Tue, 14 Jun 2011 11:33:14 +0000 (13:33 +0200)
Documentation is now buildable with setup.py build_sphinx.
Some missing components were added to make it consistent and pretty.

MANIFEST.in
doc/changes.rst [new file with mode: 0644]
doc/conf.py [new file with mode: 0644]
doc/index.rst [new file with mode: 0644]
doc/installation.rst [new file with mode: 0644]
doc/usage.rst [new file with mode: 0644]
docs/index.txt [deleted file]
docs/install.txt [deleted file]
docs/usage.txt [deleted file]

index ff6e35d..4781fc7 100644 (file)
@@ -1,5 +1,6 @@
-include COPYING 
 include CONTRIBUTORS.txt
 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/locale *.po
+recursive-include linaro_django_pagination/templates/pagination *.html
diff --git a/doc/changes.rst b/doc/changes.rst
new file mode 100644 (file)
index 0000000..5526812
--- /dev/null
@@ -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 (file)
index 0000000..39a80cb
--- /dev/null
@@ -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 (file)
index 0000000..fec8b65
--- /dev/null
@@ -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 (file)
index 0000000..8d60191
--- /dev/null
@@ -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/doc/usage.rst b/doc/usage.rst
new file mode 100644 (file)
index 0000000..d875137
--- /dev/null
@@ -0,0 +1,143 @@
+.. _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 ``&lsaquo;&lsaquo;``.
+
+``PAGINATION_NEXT_LINK_DECORATOR``
+    An HTML postfix for the next page link; the default value is ``&rsaquo;&rsaquo;``.
+
+``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.
diff --git a/docs/index.txt b/docs/index.txt
deleted file mode 100644 (file)
index b9dbafe..0000000
+++ /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 (file)
index f70d4d3..0000000
+++ /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
diff --git a/docs/usage.txt b/docs/usage.txt
deleted file mode 100644 (file)
index 756787d..0000000
+++ /dev/null
@@ -1,136 +0,0 @@
-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 ``&lsaquo;&lsaquo; ``.
-
-``NEXT_LINK_DECORATOR``
-    An HTML postfix for the next page link; the default value is `` &rsaquo;&rsaquo;``.
-
-``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.