From e5cd78d9026541e7381c1cdd7b1ddd6176c6102d Mon Sep 17 00:00:00 2001
From: Christian Schwede <info@cschwede.de>
Date: Wed, 3 Apr 2013 10:29:50 +0200
Subject: [PATCH] Update documentation for account_quota middleware

Change-Id: I3dc7930ee2a1eb26b1f60e83fce2bc1bea0a8b0f
---
 doc/source/misc.rst                       | 14 +++----
 swift/common/middleware/account_quotas.py | 51 +++++++++++++++--------
 2 files changed, 41 insertions(+), 24 deletions(-)

diff --git a/doc/source/misc.rst b/doc/source/misc.rst
index 4460d31adb..e42a91193d 100644
--- a/doc/source/misc.rst
+++ b/doc/source/misc.rst
@@ -194,6 +194,13 @@ Container Quotas
     :members:
     :show-inheritance:
 
+Account Quotas
+==============
+
+.. automodule:: swift.common.middleware.account_quotas
+    :members:
+    :show-inheritance:
+
 .. _slo-doc:
 
 Static Large Objects
@@ -209,10 +216,3 @@ List Endpoints
 .. automodule:: swift.common.middleware.list_endpoints
     :members:
     :show-inheritance:
-
-Account Quotas
-================
-
-.. automodule:: swift.common.middleware.account_quotas
-    :members:
-    :show-inheritance:
diff --git a/swift/common/middleware/account_quotas.py b/swift/common/middleware/account_quotas.py
index 211de0bc5a..8ea804cac3 100644
--- a/swift/common/middleware/account_quotas.py
+++ b/swift/common/middleware/account_quotas.py
@@ -13,7 +13,38 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-""" Account quota middleware for Openstack Swift Proxy """
+"""
+``account_quotas`` is a middleware which blocks write requests (PUT, POST) if a
+given account quota (in bytes) is exceeded while DELETE requests are still
+allowed.
+
+``account_quotas`` uses the ``x-account-meta-quota-bytes`` metadata entry to
+store the quota. Write requests to this metadata entry are only permitted for
+resellers. There is no quota limit if ``x-account-meta-quota-bytes`` is not
+set.
+
+The ``account_quotas`` middleware should be added to the pipeline in your
+``/etc/swift/proxy-server.conf`` file just after any auth middleware.
+For example::
+
+    [pipeline:main]
+    pipeline = catch_errors cache tempauth account_quotas proxy-server
+
+    [filter:account_quotas]
+    use = egg:swift#account_quotas
+
+To set the quota on an account::
+
+    swift -A http://127.0.0.1:8080/auth/v1.0 -U account:reseller -K secret \
+post -m quota-bytes:10000
+
+Remove the quota::
+
+    swift -A http://127.0.0.1:8080/auth/v1.0 -U account:reseller -K secret \
+post -m quota-bytes:
+
+"""
+
 
 from swift.common.swob import HTTPForbidden, HTTPRequestEntityTooLarge, \
     HTTPBadRequest, wsgify
@@ -22,25 +53,11 @@ from swift.proxy.controllers.base import get_account_info
 
 
 class AccountQuotaMiddleware(object):
-    """
-    account_quotas is a middleware which blocks write requests (PUT, POST) if a
-    given quota (in bytes) is exceeded while DELETE requests are still allowed.
+    """ Account quota middleware
 
-    account_quotas uses the x-account-meta-quota-bytes metadata to store the
-    quota. Write requests to this metadata setting are only allowed for
-    resellers. There is no quota limit if x-account-meta-quota-bytes is not
-    set.
-
-    The following shows an example proxy-server.conf:
-
-    [pipeline:main]
-    pipeline = catch_errors cache tempauth account-quotas proxy-server
-
-    [filter:account-quotas]
-    use = egg:swift#account_quotas
+    See above for a full description.
 
     """
-
     def __init__(self, app, *args, **kwargs):
         self.app = app