docs: add FAQ about conflicting parameters

JohnVillalovos · nejch · commit 683ce723352c · 2024-04-29T09:30:12.000+02:00
We have received multiple issues lately about this. Add it to the FAQ.
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -162,6 +162,11 @@ with the GitLab server error message:
    ...
    GitlabListError: 400: sort does not have a valid value
 
+.. _conflicting_parameters:
+
+Conflicting Parameters
+======================
+
 You can use the ``query_parameters`` argument to send arguments that would
 conflict with python or python-gitlab when using them as kwargs:
 
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -78,3 +78,23 @@ access an attribute that is shadowed by python-gitlab's own methods or managers.
 
 You can use the object's ``attributes`` dictionary to access it directly instead.
 See the :ref:`objects` section for more details on how attributes are exposed.
+
+.. _conflicting_parameters_faq:
+
+I cannot use the parameter ``path`` (or some other parameter) as it conflicts with the library
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+``path`` is used by the python-gitlab library and cannot be used as a parameter
+if wanting to send it to the GitLab instance.  You can use the
+``query_parameters`` argument to send arguments that would conflict with python
+or python-gitlab when using them as kwargs:
+
+.. code-block:: python
+
+   ## invalid, as ``path`` is interpreted by python-gitlab as the Path or full
+   ## URL to query ('/projects' or 'http://whatever/v4/api/projects')
+   project.commits.list(path='some_file_path', iterator=True)
+
+   project.commits.list(query_parameters={'path': 'some_file_path'}, iterator=True)  # OK
+
+See :ref:`Conflicting Parameters <conflicting_parameters>` for more information.
