docs: document how to use sudo if modifying an object

JohnVillalovos · JohnVillalovos · commit c70796f4b61a · 2024-07-14T23:07:27.000-07:00
Add a warning about using `sudo` when saving. Give an example of how to `get` an object, modify it, and then `save` it using `sudo` Closes: #532
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -411,6 +411,27 @@ user. For example:
 
    p = gl.projects.create({'name': 'awesome_project'}, sudo='user1')
 
+.. warning:: 
+   When using ``sudo``, its usage is not remembered. What this means is that if
+   you use ``sudo`` to retrieve an object and then later use ``save()`` to
+   modify the object it will not use ``sudo``. In that case you should do
+   ``save(sudo='user1')``
+
+Updating with ``sudo``
+----------------------
+
+An example of how to ``get`` an object (using ``sudo``), modify the object, and
+then ``save`` the object (using ``sudo``)
+
+.. code-block:: python
+
+   group = gl.groups.get('example-group')
+   notification_setting = group.notificationsettings.get(sudo='user1')
+   notification_setting.level = gitlab.const.NOTIFICATION_LEVEL_GLOBAL
+   # Must use `sudo` again when doing the save.
+   notifcation_setting.save(sudo='user1')
+
+
 Logging
 =======
 
