.. Web2py Utils documentation master file, created by
sphinx-quickstart on Tue Apr 27 21:08:49 2010.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Web2py Utils's documentation!
========================================
After using web2py for quite a while I have an eclectic mix of utilities that
I seem to be using for almost every web2py app I develop now!
I needed both a way to organize the same code across multiple web2py apps and I
also wanted to share this code with the world!
Lots of Goodies!
================
Make sure to look at the source. You may find limited documentation here.
* Common shortcuts
* py2jquery module
* Heirarchical category module.
* Database store configuration settings
* Class based menu builder
* syntax highlighting
* Output compression
* Pagination
* Stop words lists
* Levenstien algorithm
* NGram algorithm
* New SQLHTML widgets (able to pass class attributes to them)
* Convert wordpress xml export into a python dict!
* Comments, tagging, and pingback/trackback plugins!
* Unittesting, code coverage.
Installation
============
Binary
------
Install web2py_utils from the PyPi http://pypi.python.org/pypi
.. code-block:: sh
$: easy_install web2py_utils
# OR
$: pip install web2py_utils
Source
------
Do a checkout of the source code
.. code-block:: sh
$: hg clone http://hg.thadeusb.com/Web/web2py_utils
And then you can install by using setuptools
.. code-block:: sh
$: cd web2py_utils
$: python setup.py develop
.. note::
develop will make symlinks that you can continue to work off the repository
whereas install makes a copy.
Usage
=====
Once web2py_utils is installed into the path, you should import it just like any
other python module.::
import web2py_utils
From this point, you need to import everything you want explicitly. A few objects
are included in the ``web2py_utils`` namespace for convenience, however most of
the heavy lifters will be imported manual.
For example, to import the pagination library::
from web2py_utils.paginate import Pagination
Contents:
.. toctree::
:maxdepth: 2
init
auth_patches
db
menu
output
paginate
search_compare
states_years
widgets
wordpress2py
py2jquery
test_runner
License
=======
Unless otherwise noted... everything is
Copyright (C) 2009 Thadeus Burgess
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see
Contributors
============
* Mathieu Clabaut -- Doctest support for test_runner
* Francisco Gama Tabanez Ribeiro -- NCD (Normalized Compression Distance) algorithm
* Jonathan Lundell -- Documentation Editing
Contributing
============
If you would like to contribute to this project please feel free to contact
me by email! By contributing you acknowledge that your code will be released
under the GPL v3 license, unless specifically stated otherwise.
If you include any additional features to web2py_utils, please provide a patch
in mercurial changeset format. Please include any documentation to accompany your
code as well! The documentation uses sphinx and is in rEST format. I will not
include patches unless they come with documentation on usage. If you accompany
the patch with doctests and unittests will also be helpful!
To create a mercurial changeset patch, you can use the following commands
.. code-block:: sh
:$ # makes changes to code
:$ hg commit -u "Your Name " -m "Detailed description of patch"
:$ hg export tip >> /path/to/filename_describing_what_patch_does.hgchangeset.patch
You may then email the .hgchangeset.patch file directly to me.
What to Contribute
==================
If you are just looking to help contribute, but not sure what you can do here is
a list of what still needs to be done.
* Convert py2jquery documentation to reST.
* Add UnitTests to as many modules as possible
* Editing documentation
* Provide more examples of real-use case for modules