Merge pull request #482 from carbonblack/doc-fixes

Fixing guides so they can be run top to bottom

docs/alerts.rst

@@ -107,13 +107,13 @@ For example, the following snippet returns all types:
 
 .. code-block:: python
 
-    >>> alerts = cb.select(Alert).set_types([])
+    >>> alerts = api.select(Alert).set_types([])
 
 It is equivalent to:
 
 .. code-block:: python
 
-    >>> alerts = cb.select(Alert)
+    >>> alerts = api.select(Alert)
 
 .. tip::
     More information about the ``solrq`` can be found in
@@ -165,9 +165,10 @@ This first example retrieves all groupings of watchlist alerts from the past 10
     >>> api = CBCloudAPI(profile="sample")
     >>> grouped_alert_search_query = api.select(GroupedAlert)
     >>> grouped_alert_search_query = grouped_alert_search_query.set_time_range(range="-10d").add_criteria("type", "WATCHLIST").set_minimum_severity(3)
-    >>> grouped_alerts = grouped_alert_search_query.all()
-    >>> print(grouped_alerts.num_found, grouped_alerts.group_by_total_count)
-    21, 2287
+    >>> # trigger the search to execute:
+    >>> grouped_alert = grouped_alert_search_query.first()
+    >>> print("Number of groups: {}, Total alerts in all groups {}".format(grouped_alert_search_query._total_results, grouped_alert_search_query._group_by_total_count))
+    Number of groups: 19, Total alerts in all groups 2454
 
 Also like Alerts, first() can be used on the query to retrieve the first grouping of alerts and study the metadata for a given threat id.
 
@@ -179,12 +180,12 @@ Also like Alerts, first() can be used on the query to retrieve the first groupin
 
 It may be necessary to retrieve all of the alerts from a threat id grouping for further inspection, it is possible to directly retrieve the associated alert search query from a given grouped alert
 
-    >>> alert_search_query = group_alert.get_alert_search_query()
+    >>> alert_search_query = first_alert_grouping.get_alert_search_query()
     >>> alerts = alert_search_query.all()
 
 It is also possible to create grouped facets from the group alert search query
 
-    >>> grouped_alert_facets = group_alert_search_query.facets(["type", "THREAT_ID"], 0, True)
+    >>> grouped_alert_facets = grouped_alert_search_query.facets(["type", "THREAT_ID"], 0, True)
 
 Suppose instead of grouped alerts, you had been working with alerts and wanted to crossover to grouped alerts. Instead of building a new group alert query from scratch you can transform an alert search query into a grouped alert search query or vice versa!
 

docs/asset-groups.rst

@@ -24,7 +24,7 @@ Asset Groups in your organization.
     >>> from cbc_sdk.platform import AssetGroup
     >>> api = CBCloudAPI(profile='sample')
     >>> all_asset_groups = AssetGroup.get_all_groups(api)
-    >>> print("There are {} asset groups. First group: {}".format(len(all_asset_groups), all_asset_groups.first()))
+    >>> print("There are {} asset groups. First group: {}".format(len(all_asset_groups), all_asset_groups[0]))
     There are 1 asset groups. This is the first: AssetGroup object, bound to https://defense.conferdeploy.net.
      Partially initialized. Use .refresh() to load all attributes
     -------------------------------------------------------------------------------
@@ -60,7 +60,7 @@ Summary information for each asset group is printed, and then the devices in tha
     Device Name: DemoDevice, Id: 2468642
     Device Name: SDKDemo, Id: 1357975
     Device Name: AnotherDemoMachine, Id: 19283746
-    ... truncated ...
+        ...truncated ...
 
 Create an Asset Group
 ---------------------
@@ -99,10 +99,14 @@ finished updating.
 * ``OK`` indicates the membership evaluation is complete
 * ``UPDATING`` indicates that group’s dynamic memberships are being re-evaluated
 
+    >>> import time
     >>> while new_asset_group.status != "OK":
     >>>     print("waiting")
     >>>     time.sleep(5)
     >>>     new_asset_group.refresh()
+
+Then print the new asset:
+
     >>> print("new_asset_group {}".format(new_asset_group))
     new_asset_group, bound to https://defense.conferdeploy.net.
      Last refreshed at Tue Jan 23 22:47:47 2024
@@ -131,6 +135,7 @@ All attributes can also be provided to the create method:
 The add_member() function is used to assign a device directly to the group. (Compared to dynamically added, when the
 device matches the query on the asset group.)
 
+    >>> from cbc_sdk.platform import Device
     >>> random_device = api.select(Device).first()
     >>> second_asset_group.add_members(random_device)
 
@@ -156,11 +161,13 @@ The preview method is a static class method on Policy, since it is a policy chan
 The result is a :py:mod:`DevicePolicyChangePreview() <cbc_sdk.platform.previewer.DevicePolicyChangePreview>` class,
 which contains information about all the device that would have a change in effective policy.
 
+    >>> from cbc_sdk.platform import Policy
     >>> api = CBCloudAPI(profile='sample')
     >>> policy_id = 1234
     >>> # to get a policy that exists in your org: policy_id = api.select(Policy).first().id
     >>> new_policy_position = 1
     >>> changes = Policy.preview_policy_rank_changes(api, [(policy_id, new_policy_position)])
+    >>> print(changes[0])
     DevicePolicyChangePreview object, bound to https://defense.conferdeploy.net.
     -------------------------------------------------------------------------------
     Current policy: #98765 at rank 7
@@ -195,8 +202,7 @@ Here we're working with a random asset group and policy, using the ``first()`` f
 A new policy is assigned and the existing query is not changed.
 
     >>> asset_group = api.select(AssetGroup).first()
-    >>> policy_id = api.select(Policy).first()
-    >>> new_policy_position = 1
+    >>> policy_id = api.select(Policy).first().id
     >>> api = CBCloudAPI(profile='sample')
     >>> changes = AssetGroup.preview_update_asset_groups(api, [asset_group], policy_id, asset_group.query)
     >>> print("There are {} changes that would result from the proposed change. The first change:".format(len(changes)))

docs/changelog.rst

@@ -39,6 +39,12 @@ Bug Fixes:
 * Search jobs that allow setting a timeout now default that timeout to 5 minutes.  The timeout may be lowered
   from that point, but *never* raised beyond it.  This eliminates a problem of "hung" searches.
 
+Documentation:
+* ReadTheDocs generation has been improved to show the inherited methods.  There are some helper functions on
+SearchQuery classes such as add_criteria() inherited from CriteriaBuilderSupportMixin and first() inherited from
+IterableQueryMixin.
+
+
 CBC SDK 1.5.0 - Released October 24, 2023
 -----------------------------------------