Update documentation

docs/api_reference.rst

@@ -19,12 +19,17 @@ Blueprint
 .. autoclass:: flask_rest_api.Blueprint
     :members:
 
+    .. automethod:: arguments
+    .. automethod:: response
+    .. automethod:: paginate
+
 Pagination
 ==========
 
 .. autoclass:: flask_rest_api.Page
     :members:
-.. autofunction:: flask_rest_api.set_item_count
+.. autoclass:: flask_rest_api.pagination.PaginationParameters
+    :members:
 
 ETag
 ====

docs/parameters.rst → docs/arguments.rst

@@ -1,10 +1,11 @@
-.. _parameters:
+.. _arguments:
 .. module:: flask_rest_api
 
-Parameters
-==========
+Arguments
+=========
 
-To inject parameters into a view function, use the :meth:`Blueprint.arguments <Blueprint.arguments>` decorator.
+To inject arguments into a view function, use the :meth:`Blueprint.arguments
+<Blueprint.arguments>` decorator.
 
 This method takes a :class:`Schema <marshmallow.Schema>` to deserialize and
 validate the parameters.

docs/index.rst

@@ -28,7 +28,7 @@ Guide
     :maxdepth: 1
 
     quickstart
-    parameters
+    arguments 
     response
     pagination
     etag

docs/pagination.rst

@@ -15,16 +15,17 @@ Pagination in the View Function
 -------------------------------
 
 In this mode, :meth:`Blueprint.paginate <Blueprint.paginate>` injects the
-pagination parameters ``first_item`` and ``last_item`` as kwargs into the view
-function.
+pagination parameters into the view function as a
+:class:`PaginationParameters <pagination.PaginationParameters>` object passed
+as ``pagination_parameters`` keyword argument.
 
 It is the responsability of the view function to return only selected elements.
 
-The view function must also specify the total number of elements using
-:meth:`set_item_count <pagination.set_item_count>`.
+The view function must also specify the total number of elements by setting it
+as ``item_count`` attribute of the `PaginationParameters` object.
 
 .. code-block:: python
-    :emphasize-lines: 7,8,9,10
+    :emphasize-lines: 7,8,9,10,11,12
 
     from flask_rest_api import set_item_count
 
@@ -33,9 +34,11 @@ The view function must also specify the total number of elements using
 
         @blp.response(PetSchema(many=True))
         @blp.paginate()
-        def get(self, first_item, last_item):
-            set_item_count(Pet.size)
-            return Pet.get_elements(first_item=first_item, last_item=last_item)
+        def get(self, pagination_parameters):
+            pagination_parameters.item_count = Pet.size
+            return Pet.get_elements(
+                first_item=pagination_parameters.first_item,
+                last_item=pagination_parameters.last_item)
 
 
 Post-Pagination
@@ -98,15 +101,15 @@ specific range of data by passing query arguments:
 The view function gets default values for the pagination parameters, as well as
 a maximum value for ``page_size``.
 
-Those default values are defined globally as
+Those default values are defined as
 
 .. code-block:: python
 
     DEFAULT_PAGINATION_PARAMETERS = {
         'page': 1, 'page_size': 10, 'max_page_size': 100}
 
-They can be modified globally by mutating
-``flask_rest_api.pagination.DEFAULT_PAGINATION_PARAMETERS``, or overwritten in
+They can be modified globally by overriding ``DEFAULT_PAGINATION_PARAMETERS``
+class attribute of the :class:`Blueprint <Blueprint>` class or overridden in
 a specific view function by passing them as keyword arguments to
 :meth:`Blueprint.paginate <Blueprint.paginate>`.
 
@@ -125,3 +128,8 @@ It contains the pagination information.
     #     'page': 2, 'first_page': 1, 'last_page': 200,
     #     'previous_page': 1, 'next_page': 3,
     # }
+
+The name of the header can be changed by overriding
+``PAGINATION_HEADER_FIELD_NAME`` class attribute of the
+:class:`Blueprint <Blueprint>` class. When setting this attribute to ``None``,
+no pagination header is added to the response.

flask_rest_api/arguments.py

@@ -59,10 +59,9 @@ def arguments(self, schema, *, location='json', required=True, **kwargs):
 
         :param type|Schema schema: A marshmallow Schema class or instance.
         :param str location: The location of the parameter, in webargs terms.
-            https://webargs.readthedocs.io/en/latest/quickstart.html#request-locations
-            Allows values: 'query' or 'querystring', 'json', 'form', 'headers',
-            'cookies', 'files'.
-            Defaults to 'json', which means 'body'.
+            Full list available in `webargs documentation
+            <https://webargs.readthedocs.io/en/latest/quickstart.html#request-locations>`_.
+            Defaults to ``'json'``, which means `body`.
             Note that unlike webargs, flask-rest-api allows only one location
             for a parameter.
         :param bool required: Whether this set of arguments is required.
@@ -72,7 +71,9 @@ def arguments(self, schema, *, location='json', required=True, **kwargs):
             For other locations, the schema is turned into an array of
             parameters and their required value is grabbed from their Field.
 
-        The kwargs are passed to webargs's Parser.use_args.
+        The kwargs are passed to the `use_args` method of the
+        :class:`webargs FlaskParser <webargs.flaskparser.FlaskParser>` used
+        internally to parse the arguments.
 
         Upon endpoint access, the parameters are deserialized into a dictionary
         that is injected as a positional argument to the view function.
@@ -89,6 +90,8 @@ def post(document, query_args):
 
         The order of the decorator calls matter as it determines the order in
         which the parameters are passed to the view function.
+
+        See :doc:`Arguments <arguments>`.
         """
         # TODO: This shouldn't be needed. I think I did this because apispec
         # worked better with instances, but this should have been solved since.

flask_rest_api/pagination.py

@@ -26,8 +26,11 @@
 
 
 class PaginationParameters:
-    """Holds pagination arguments"""
+    """Holds pagination arguments
 
+    :param int page: Page number
+    :param int page_size: Page size
+    """
     def __init__(self, page, page_size):
         self.page = page
         self.page_size = page_size
@@ -132,12 +135,15 @@ def paginate(self, pager=None, *,
 
         If no pager class is provided, pagination is handled in the view
         function. The view function is passed a
-        :class:`pagination.PaginationParameters` <PaginationParameters>
-        instance as `pagination_parameters` keyword parameter.
-        This object provides pagination parameters as both `page`/`page_size`
-        and `first_item`/`last_item`. The view function is responsible for
-        storing the total number of items as `item_count` attribute of passed
-        `PaginationParameters` instance.
+        :class:`pagination.PaginationParameters
+        <pagination.PaginationParameters>`
+        instance as ``pagination_parameters`` keyword parameter.
+        This object provides pagination parameters as both
+        ``page``/``page_size`` and ``first_item``/``last_item``.
+        The view function is responsible for storing the total number of items
+        as ``item_count`` attribute of the ``PaginationParameters`` instance.
+
+        See :doc:`Pagination <pagination>`.
         """
         if page is None:
             page = self.DEFAULT_PAGINATION_PARAMETERS['page']

flask_rest_api/response.py

@@ -34,6 +34,8 @@ def response(self, schema=None, *, code=200, description='',
 
                 @blp.response(MySchema(many=True), description: 'My objects')
                 def get(...)
+
+        See :doc:`Response <response>`.
         """
         if isinstance(schema, type):
             schema = schema()