May 29, 2022 · May 29, 2022
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
 .. code-block:: python

   # list all the projects
   projects = gl.projects.list()
   projects = gl.projects.list(as_list=False)
   for project in projects:
       print(project)

   # get the group with id == 2
   group = gl.groups.get(2)
   for project in group.projects.list():
   for project in group.projects.list(as_list=False):
       print(project)

   # create a new user
   user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
   user = gl.users.create(user_data)
   print(user)

 .. warning::
   Calling ``list()`` without any arguments will by default not return the complete list
   of items. Use either the ``all=True`` or ``as_list=False`` parameters to get all the
   items when using listing methods. See the :ref:`pagination` section for more
   information.

 You can list the mandatory and optional attributes for object creation and
 update with the manager's ``get_create_attrs()`` and ``get_update_attrs()``
 methods. They return 2 tuples, the first one is the list of mandatory

   # list the issues for a project
   project = gl.projects.get(1)
   issues = project.issues.list()
   issues = project.issues.list(all=True)

 python-gitlab allows to send any data to the GitLab server when making queries.
 In case of invalid or missing arguments python-gitlab will raise an exception

 .. code-block:: python

   gl.user_activities.list(from='2019-01-01')  ## invalid
   gl.user_activities.list(from='2019-01-01', as_list=False)  ## invalid

   gl.user_activities.list(query_parameters={'from': '2019-01-01'})  # OK
   gl.user_activities.list(query_parameters={'from': '2019-01-01'}, as_list=False)  # OK

 Gitlab Objects
 ==============
   project = gl.projects.get(1, lazy=True)  # no API call
   project.star()  # API call

 .. _pagination:

 Pagination
 ==========
Original file line number	Diff line number	Diff line change
Expand Up		@@ -93,20 +93,26 @@ Examples:
		.. code-block:: python

		# list all the projects
		projects = gl.projects.list()
		projects = gl.projects.list(as_list=False)
		for project in projects:
		print(project)

		# get the group with id == 2
		group = gl.groups.get(2)
		for project in group.projects.list():
		for project in group.projects.list(as_list=False):
nejch marked this conversation as resolved. Show resolvedHide resolved
		print(project)

		# create a new user
		user_data = {'email': 'jen@foo.com', 'username': 'jen', 'name': 'Jen'}
		user = gl.users.create(user_data)
		print(user)

		.. warning::
		Calling ``list()`` without any arguments will by default not return the complete list
		of items. Use either the ``all=True`` or ``as_list=False`` parameters to get all the
		items when using listing methods. See the :ref:`pagination` section for more
		information.

		You can list the mandatory and optional attributes for object creation and
		update with the manager's ``get_create_attrs()`` and ``get_update_attrs()``
		methods. They return 2 tuples, the first one is the list of mandatory
Expand All		@@ -133,7 +139,7 @@ Some objects also provide managers to access related GitLab resources:

		# list the issues for a project
		project = gl.projects.get(1)
		issues = project.issues.list()
		issues = project.issues.list(all=True)

		python-gitlab allows to send any data to the GitLab server when making queries.
		In case of invalid or missing arguments python-gitlab will raise an exception
Expand All		@@ -150,9 +156,9 @@ conflict with python or python-gitlab when using them as kwargs:

		.. code-block:: python

		gl.user_activities.list(from='2019-01-01') ## invalid
		gl.user_activities.list(from='2019-01-01', as_list=False) ## invalid

		gl.user_activities.list(query_parameters={'from': '2019-01-01'}) # OK
		gl.user_activities.list(query_parameters={'from': '2019-01-01'}, as_list=False) # OK

		Gitlab Objects
		==============
Expand DownExpand Up		@@ -233,6 +239,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
		==========

Expand Down