docs(faq): describe and group common errors

2 files changed, 86 insertions, 46 deletions

diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 444064b..06b9058 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -171,6 +171,8 @@ conflict with python or python-gitlab when using them as kwargs:
 
    gl.user_activities.list(query_parameters={'from': '2019-01-01'}, iterator=True)  # OK
 
+.. _objects:
+
 Gitlab Objects
 ==============
 
@@ -220,21 +222,16 @@ the value on the object is accepted:
       issue.my_super_awesome_feature_flag = "random_value"
       issue.save()
 
+As a dictionary
+---------------
+
 You can get a dictionary representation copy of the Gitlab Object. Modifications made to
 the dictionary will have no impact on the GitLab Object.
 
- * ``asdict()`` method. Returns a dictionary representation of the Gitlab object.
- * ``attributes`` property. Returns a dictionary representation of the Gitlab
+* ``asdict()`` method. Returns a dictionary representation of the Gitlab object.
+* ``attributes`` property. Returns a dictionary representation of the Gitlab
    object. Also returns any relevant parent object attributes.
 
-.. note::
-
-   ``attributes`` returns the parent object attributes that are defined in
-   ``object._from_parent_attrs``. What this can mean is that for example a ``ProjectIssue``
-   object will have a ``project_id`` key in the dictionary returned from ``attributes`` but
-   ``asdict()`` will not.
-
-
 .. code-block:: python
 
    project = gl.projects.get(1)
@@ -244,6 +241,22 @@ the dictionary will have no impact on the GitLab Object.
    issue = project.issues.get(1)
    attribute_dict = issue.attributes
 
+   # The following will return the same value
+   title = issue.title
+   title = issue.attributes["title"]
+
+.. hint::
+
+   This can be used to access attributes that clash with python-gitlab's own methods or managers.
+   Note that:
+
+   ``attributes`` returns the parent object attributes that are defined in
+   ``object._from_parent_attrs``. For example, a ``ProjectIssue`` object will have a
+   ``project_id`` key in the dictionary returned from ``attributes`` but ``asdict()`` will not.
+
+As JSON
+-------
+
 You can get a JSON string represenation of the Gitlab Object. For example:
 
 .. code-block:: python
diff --git a/docs/faq.rst b/docs/faq.rst
index 3f2ee6c..cd4734a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -2,52 +2,79 @@
 FAQ
 ###
 
-I cannot edit the merge request / issue I've just retrieved
-    It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
-    ``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you
-    can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
-    apply changes. For example::
+General
+-------
 
-        issue = gl.issues.list()[0]
-        project = gl.projects.get(issue.project_id, lazy=True)
-        editable_issue = project.issues.get(issue.iid, lazy=True)
-        # you can now edit the object
+I cannot edit the merge request / issue I've just retrieved.
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-    See the :ref:`merge requests example <merge_requests_examples>` and the
-    :ref:`issues examples <issues_examples>`.
+It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
+``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you
+can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
+apply changes. For example::
 
-.. _attribute_error_list:
+    issue = gl.issues.list()[0]
+    project = gl.projects.get(issue.project_id, lazy=True)
+    editable_issue = project.issues.get(issue.iid, lazy=True)
+    # you can now edit the object
+
+See the :ref:`merge requests example <merge_requests_examples>` and the
+:ref:`issues examples <issues_examples>`.
 
-I get an ``AttributeError`` when accessing attributes of an object retrieved via a ``list()`` call.
-    Fetching a list of objects, doesn’t always include all attributes in the
-    objects. To retrieve an object with all attributes use a ``get()`` call.
+How can I clone the repository of a project?
+""""""""""""""""""""""""""""""""""""""""""""
 
-    Example with projects::
+python-gitlab does not provide an API to clone a project. You have to use a
+git library or call the ``git`` command.
 
-        for projects in gl.projects.list():
-            # Retrieve project object with all attributes
-            project = gl.projects.get(project.id)
+The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project``
+objects.
 
-How can I clone the repository of a project?
-    python-gitlab doesn't provide an API to clone a project. You have to use a
-    git library or call the ``git`` command.
+Example::
+
+    import subprocess
+
+    project = gl.projects.create(data)  # or gl.projects.get(project_id)
+    print(project.attributes)  # displays all the attributes
+    git_url = project.ssh_url_to_repo
+    subprocess.call(['git', 'clone', git_url])
+
+Not all items are returned from the API
+"""""""""""""""""""""""""""""""""""""""
+
+If you've passed ``all=True`` (or ``--all`` via the CLI) to the API and still cannot see all items returned,
+use ``get_all=True`` (or ``--get-all`` via the CLI) instead. See :ref:`pagination` for more details.
+
+Common errors
+-------------
+
+.. _attribute_error_list:
+
+``AttributeError`` when accessing object attributes retrieved via ``list()``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Fetching a list of objects does not always include all attributes in the objects.
+To retrieve an object with all attributes, use a ``get()`` call.
+
+Example with projects::
 
-    The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project``
-    objects.
+    for projects in gl.projects.list():
+        # Retrieve project object with all attributes
+        project = gl.projects.get(project.id)
 
-    Example::
+``AttributeError`` when accessing attributes after ``save()`` or ``refresh()``
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-        import subprocess
+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.
 
-        project = gl.projects.create(data)  # or gl.projects.get(project_id)
-        print(project.attributes)  # displays all the attributes
-        git_url = project.ssh_url_to_repo
-        subprocess.call(['git', 'clone', git_url])
+``TypeError`` when accessing object attributes
+""""""""""""""""""""""""""""""""""""""""""""""
 
-I get an ``AttributeError`` when accessing attributes after ``save()`` or ``refresh()``.
-    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.
+When you encounter errors such as ``object is not iterable`` or ``object is not subscriptable``
+when trying to access object attributes returned from the server, you are most likely trying to
+access an attribute that is shadowed by python-gitlab's own methods or managers.
 
-I passed ``all=True`` (or ``--all`` via the CLI) to the API and I still cannot see all items returned.
-    Use ``get_all=True`` (or ``--get-all`` via the CLI). See :ref:`pagination` for more details.
+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.