Merge pull request #368 from digitalocean/update-docs

update docs

Author: Zach Moody

docs/response.rst

@@ -2,4 +2,7 @@ Response
 ========
 
 .. autoclass:: pynetbox.core.response.Record
-  :members:
+  :members:
+
+.. autoclass:: pynetbox.core.response.RecordSet
+  :members:

pynetbox/core/endpoint.py

@@ -79,12 +79,17 @@ def all(self, limit=0):
         :arg int,optional limit: Overrides the max page size on
             paginated returns.
 
-        :Returns: List of :py:class:`.Record` objects.
+        :Returns: A :py:class:`.RecordSet` object.
 
         :Examples:
 
-        >>> nb.dcim.devices.all()
-        [test1-a3-oobsw2, test1-a3-oobsw3, test1-a3-oobsw4]
+        >>> devices = nb.dcim.devices.all()
+        >>> for device in devices:
+        ...     print(device.name)
+        ...
+        test1-leaf1
+        test1-leaf2
+        test1-leaf3
         >>>
         """
         req = Request(
@@ -176,33 +181,50 @@ def filter(self, *args, **kwargs):
         :arg int,optional limit: Overrides the max page size on
             paginated returns.
 
-        :Returns: A list of :py:class:`.Record` objects.
+        :Returns: A :py:class:`.RecordSet` object.
 
         :Examples:
 
         To return a list of objects matching a named argument filter.
 
-        >>> nb.dcim.devices.filter(role='leaf-switch')
-        [test1-a3-tor1b, test1-a3-tor1c, test1-a3-tor1d, test1-a3-tor2a]
+        >>> devices = nb.dcim.devices.filter(role='leaf-switch')
+        >>> for device in devices:
+        ...     print(device.name)
+        ...
+        test1-leaf1
+        test1-leaf2
+        test1-leaf3
         >>>
 
         Using a freeform query along with a named argument.
 
-        >>> nb.dcim.devices.filter('a3', role='leaf-switch')
-        [test1-a3-tor1b, test1-a3-tor1c, test1-a3-tor1d, test1-a3-tor2a]
+        >>> devices = nb.dcim.devices.filter('a3', role='leaf-switch')
+        >>> for device in devices:
+        ...     print(device.name)
+        ...
+        test1-a3-leaf1
+        test1-a3-leaf2
         >>>
 
         Chaining multiple named arguments.
 
-        >>> nb.dcim.devices.filter(role='leaf-switch', status=True)
-        [test1-leaf2]
+        >>> devices = nb.dcim.devices.filter(role='leaf-switch', status=True)
+        >>> for device in devices:
+        ...     print(device.name)
+        ...
+        test1-leaf2
         >>>
 
         Passing a list as a named argument adds multiple filters of the
         same value.
 
-        >>> nb.dcim.devices.filter(role=['leaf-switch', 'spine-switch'])
-        [test1-a3-spine1, test1-a3-spine2, test1-a3-leaf1]
+        >>> device = nb.dcim.devices.filter(role=['leaf-switch', 'spine-switch'])
+        >>> for device in devices:
+        ...     print(device.name)
+        ...
+        test1-a3-spine1
+        test1-a3-spine2
+        test1-a3-leaf1
         >>>
         """
 
@@ -251,10 +273,9 @@ def create(self, *args, **kwargs):
 
         :Examples:
 
-        Creating an object on the `devices` endpoint you can lookup a
-        device_role's name with:
+        Creating an object on the `devices` endpoint:
 
-        >>> netbox.dcim.devices.create(
+        >>> device = netbox.dcim.devices.create(
         ...    name='test',
         ...    device_role=1,
         ... )

pynetbox/core/response.py

@@ -71,6 +71,34 @@ class JsonField(object):
 
 
 class RecordSet(object):
+    """Iterator containing Record objects.
+
+    Returned by :py:meth:`.Endpoint.all()` and :py:meth:`.Endpoint.filter()` methods.
+    Allows iteration of and actions to be taken on the results from the aforementioned
+    methods. Contains :py:class:`.Record` objects.
+
+    :Examples:
+
+    To see how many results are in a query by calling ``len()``.
+
+    >>> x = nb.dcim.devices.all()
+    >>> len(x)
+    123
+    >>>
+
+    Simple iteration of the results.
+
+    >>> devices = nb.dcim.devices.all()
+    >>> for device in devices:
+    ...     print(device.name)
+    ...
+    test1-leaf1
+    test1-leaf2
+    test1-leaf3
+    >>>
+
+    """
+
     def __init__(self, endpoint, request, **kwargs):
         self.endpoint = endpoint
         self.request = request