docs: Update download_dashboards example and get_dashboards documentation (#178)

Author: tembleking

examples/download_dashboards.py

@@ -56,7 +56,7 @@ def cleanup_dir(path):
 #
 # Fire the request.
 #
-ok, res = sdclient.get_dashboards()
+ok, res = sdclient.get_dashboards(light=False)
 
 #
 # Show the list of dashboards

sdcclient/monitor/_dashboards_v3.py

@@ -46,15 +46,29 @@ def get_view(self, name):
         return self._request_result(res)
 
     def get_dashboards(self, light=True):
-        '''**Description**
-            Return the list of dashboards available under the given user account. This includes the dashboards created by the user and the ones shared with her by other users.
-
-        **Success Return Value**
-            A dictionary containing the list of available sampling intervals.
-
-        **Example**
-            `examples/list_dashboards.py <https://github.com/draios/python-sdc-client/blob/master/examples/list_dashboards.py>`_
-        '''
+        """
+        Return the list of dashboards available under the given user account.
+        This includes the dashboards created by the user and the ones shared with her by other users.
+        Since every user has multiple tokens -- one per team they are assigned to -- and dashboards are scoped per
+        team, in order to download all the dashboards from a user account, all the tokens must be specified.
+
+        Args:
+            light (bool): If it's true, only a small portion of information will be retrieved, otherwise all
+                          the information from the dashboards will be retrieved.
+                          If the retrieved dashboards are going to be restored in the future, then this
+                          parameter must be false.
+
+        Returns:
+            The list of the dashboards visible for the given token.
+
+        See Also:
+            :py:meth:`~.DashboardsClientV3.create_dashboard_with_configuration`
+
+        Examples:
+            >>> ok, res = client.get_dashboards(light=False)
+            >>> for dashboard in res["dashboards"]:
+            >>>     print(dashboard["name"])
+        """
         params = {
             "light": "true" if light else "false"
         }