fix(api): add all_pages param to allow passing `all` to APIfix/all-pages-consumes-all-param

3 files changed, 19 insertions, 2 deletions

diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index e911664..3bf4354 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -190,6 +190,8 @@ a project (the previous example used 2 API calls):
    project = gl.projects.get(1, lazy=True)  # no API call
    project.star()  # API call
 
+.. _pagination:
+
 Pagination
 ==========
 
@@ -205,11 +207,16 @@ listing methods support the ``page`` and ``per_page`` parameters:
    The first page is page 1, not page 0.
 
 By default GitLab does not return the complete list of items. Use the ``all``
-parameter to get all the items when using listing methods:
+parameter to get all the items when using listing methods. Alternatively, if
+the endpoint also accepts an ``all`` parameter itself, you can use the
+``all_pages`` parameter for listing methods to avoid this conflict:
 
 .. code-block:: python
 
    all_groups = gl.groups.list(all=True)
+   # or
+   all_groups = gl.groups.list(all_pages=True)
+
    all_owned_projects = gl.projects.list(owned=True, all=True)
 
 You can define the ``per_page`` value globally to avoid passing it to every
diff --git a/docs/faq.rst b/docs/faq.rst
index 0f914ed..834420d 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -36,3 +36,8 @@ I get an ``AttributeError`` when accessing attributes after ``save()`` or ``refr
     You are most likely trying to access an attribute that was not returned
     by the server on the second request. Please look at the documentation in
     :ref:`object_attributes` to see how to avoid this.
+
+I passed ``all=True`` (or ``--all`` via the CLI) to the API and I still cannot see all items returned.
+    In some cases, API endpoints take an ``all`` parameter that conflicts with python-gitlab's
+    own ``all`` used with pagination. Use ``all_pages=True`` (or ``--all-pages`` via the CLI) along
+    with ``all=True`` to really fetch all items in this case. See :ref:`pagination` for more details.
diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst
index a1d878c..550658b 100644
--- a/docs/gl_objects/commits.rst
+++ b/docs/gl_objects/commits.rst
@@ -30,7 +30,12 @@ results::
 .. note::
 
    The available ``all`` listing argument conflicts with the python-gitlab
-   argument. Use ``query_parameters`` to avoid the conflict::
+   argument. Use the ``all_pages`` argument to return all paginated items
+   if you need to pass ``all`` to the API:
+
+        commits = project.commits.list(all_pages=True, all=True)
+
+   Alternatively, use ``query_parameters`` to specify the parameters::
 
        commits = project.commits.list(all=True,
                                       query_parameters={'ref_name': 'my_branch'})