docs fix potpourri (#178)

* fix is_scene docs; polygon param; stray ds IDs

* lint

* add list_jobs params

* rm test artifact

Author: drakejwong

nucleus/__init__.py

@@ -236,6 +236,12 @@ def list_jobs(
     ) -> List[AsyncJob]:
         """Fetches all of your running jobs in Nucleus.
 
+        Parameters:
+            show_completed: Whether to fetch completed and errored jobs or just
+              running jobs. Default behavior is False.
+            date_limit: Only fetch jobs that were started after this date. Default
+              behavior is 2 weeks prior to the current date.
+
         Returns:
             List[:class:`AsyncJob`]: List of running asynchronous jobs
             associated with the client API key.
@@ -344,13 +350,13 @@ def create_dataset(
         Creates a new, empty dataset.
 
         Make sure that the dataset is created for the data type you would like to support.
-        Be aware to set the `is_scene` correctly.
+        Be sure to set the ``is_scene`` parameter correctly.
 
         Parameters:
             name: A human-readable name for the dataset.
-            is_scene: Boolean specifying if the dataset type. This value is immutable.
-                     `False` will allow users to uplaod :class:`DatasetItems<DatasetItem>`s.
-                     `True` will allow users to upload :class:`Scenes<LidarScene>`s.
+            is_scene: Whether the dataset contains strictly :class:`scenes
+              <LidarScene>` or :class:`items <DatasetItem>`. This value is immutable.
+              Default is False (dataset of items).
             item_metadata_schema: Dict defining item-level metadata schema. See below.
             annotation_metadata_schema: Dict defining annotation-level metadata schema.
 

nucleus/annotation.py

@@ -195,7 +195,7 @@ class PolygonAnnotation(Annotation):
 
     Parameters:
         label (str): The label for this annotation.
-        vertices List[:class:`Point`]: The list of points making up the polygon.
+        vertices (List[:class:`Point`]): The list of points making up the polygon.
         reference_id (str): User-defined ID of the image to which to apply this
             annotation.
         annotation_id (Optional[str]): The annotation ID that uniquely identifies

nucleus/dataset.py

@@ -97,7 +97,7 @@ class Dataset:
 
         # Or, retrieve existing dataset by ID
         # This ID can be fetched using client.list_datasets() or from a dashboard URL
-        existing_dataset = client.get_dataset("ds_bwkezj6g5c4g05gqp1eg")
+        existing_dataset = client.get_dataset("YOUR_DATASET_ID")
     """
 
     def __init__(self, dataset_id, client, name=None):
@@ -396,20 +396,19 @@ def append(
     ) -> Union[Dict[Any, Any], AsyncJob, UploadResponse]:
         """Appends items or scenes to a dataset.
 
-        Attention (!!!)
-        You will only be able to add :class:`DatasetItems<DatasetItem>`s to a dataset supporting "
-        ":class:`DatasetItems<DatasetItem>`s.
-        Also, you will only be able to add :class:`Scenes<LidarScene>`s to a dataset supporting "
-        ":class:`Scenes<LidarScene>`s.
-        A :class:`DatasetItems<DatasetItem>` dataset can be created with the is_scene flag set to False.
-        A :class:`Scenes<LidarScene>` dataset can be created with the is_scene flag set to True.
+        .. note::
+            Datasets can only accept one of :class:`DatasetItems <DatasetItem>`
+            or :class:`Scenes <LidarScene>`, never both.
+
+            This behavior is set during Dataset :meth:`creation
+            <NucleusClient.create_dataset>` with the ``is_scene`` flag.
 
         ::
 
             import nucleus
 
-            client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
-            dataset = client.get_dataset("ds_bwkezj6g5c4g05gqp1eg")
+            client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+            dataset = client.get_dataset("YOUR_DATASET_ID")
 
             local_item = nucleus.DatasetItem(
               image_location="./1.jpg",
@@ -762,8 +761,8 @@ def create_custom_index(
 
             import nucleus
 
-            client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
-            dataset = client.get_dataset("ds_bwkezj6g5c4g05gqp1eg")
+            client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+            dataset = client.get_dataset("YOUR_DATASET_ID")
 
             embeddings = {
                 "reference_id_0": [0.1, 0.2, 0.3],
@@ -907,8 +906,8 @@ def add_taxonomy(
         ::
 
             import nucleus
-            client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
-            dataset = client.get_dataset("ds_bwkezj6g5c4g05gqp1eg")
+            client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+            dataset = client.get_dataset("YOUR_DATASET_ID")
 
             response = dataset.add_taxonomy(
                 taxonomy_name="clothing_type",
@@ -1076,12 +1075,12 @@ def calculate_evaluation_metrics(self, model, options: dict = None):
 
             import nucleus
 
-            client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
-            dataset = client.get_dataset(dataset_id="ds_bwkezj6g5c4g05gqp1eg")
+            client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+            dataset = client.get_dataset(dataset_id="YOUR_DATASET_ID")
 
             model = client.get_model(
-                model_id="prj_bybpa3gjmjc30es761y0",
-                dataset_id="ds_bwkezj6g5c4g05gqp1eg"
+                model_id="YOUR_MODEL_PRJ_ID",
+                dataset_id="YOUR_DATASET_ID"
             )
 
             # Compute all evaluation metrics including IOU-based matching:

nucleus/modelci/data_transfer_objects/eval_function.py

@@ -41,6 +41,6 @@ class EvalFunctionEntry(ImmutableModel):
 
 
 class GetEvalFunctions(ImmutableModel):
-    """ Expected format from GET modelci/eval_fn"""
+    """Expected format from GET modelci/eval_fn"""
 
     eval_functions: List[EvalFunctionEntry]

nucleus/modelci/data_transfer_objects/unit_test_metric.py

@@ -4,7 +4,7 @@
 
 
 class AddUnitTestMetric(ImmutableModel):
-    """ Data transfer object to add a unit test."""
+    """Data transfer object to add a unit test."""
 
     unit_test_name: str
     eval_function_id: str

nucleus/slice.py

@@ -30,8 +30,8 @@ class Slice:
 
         import nucleus
 
-        client = nucleus.NucleusClient(YOUR_SCALE_API_KEY)
-        dataset = client.get_dataset("ds_bwkezj6g5c4g05gqp1eg")
+        client = nucleus.NucleusClient("YOUR_SCALE_API_KEY")
+        dataset = client.get_dataset("YOUR_DATASET_ID")
 
         ref_ids = ["interesting_item_1", "interesting_item_2"]
         slice = dataset.create_slice(name="interesting", reference_ids=ref_ids)