DOCS-2425: Merge autogen: mlmodel, motion

.github/workflows/update_sdk_methods.py

@@ -412,6 +412,8 @@
     "bool": "https://docs.python.org/3/library/stdtypes.html#boolean-type-bool",
     "datetime.datetime": "https://docs.python.org/3/library/datetime.html",
     "datetime.timedelta": "https://docs.python.org/3/library/datetime.html#timedelta-objects",
+    ## Third-party data types:
+    "numpy.typing.NDArray": "https://numpy.org/doc/stable/reference/typing.html#numpy.typing.NDArray",
     ## Viam-specific data types:
     "viam.proto.app.OrganizationMember": "https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.OrganizationMember",
     "viam.proto.app.OrganizationInvite": "https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.OrganizationInvite",
@@ -1574,8 +1576,9 @@ def format_method_usage(parsed_usage_string, go_method_name, resource, path_to_m
             ## If we have a param description override, use that. If not, skip:
             if param_or_return_description != '':
 
-                ## Add a trailing period if it is missing, either from upstream or from override file:
-                if not param_or_return_description.endswith('.'):
+                ## Add a trailing period if it is missing, either from upstream or from override file,
+                ## but skip doing so if the copy instead ends with an HTML tag (like a closing '</ul>' tag):
+                if not param_or_return_description.endswith('.') and not param_or_return_description.endswith('>'):
                     param_or_return_description = param_or_return_description + '.'
 
                 ## Format returns:
@@ -1810,8 +1813,9 @@ def write_markdown(type, names, methods):
 
                                     if param_description:
 
-                                        ## Add a trailing period if it is missing, either from upstream or from override file:
-                                        if not param_description.endswith('.'):
+                                        ## Add a trailing period if it is missing, either from upstream or from override file,
+                                        ## but skip doing so if the copy instead ends with an HTML tag (like a closing '</ul>' tag):
+                                        if not param_description.endswith('.') and not param_description.endswith('>'):
                                             param_description = param_description + '.'
 
                                         output_file.write(f": {param_description}")
@@ -1855,8 +1859,9 @@ def write_markdown(type, names, methods):
 
                                     if return_description:
 
-                                        ## Add a trailing period if it is missing, either from upstream or from override file:
-                                        if not return_description.endswith('.'):
+                                        ## Add a trailing period if it is missing, either from upstream or from override file,
+                                        ## but skip doing so if the copy instead ends with an HTML tag (like a closing '</ul>' tag):
+                                        if not return_description.endswith('.') and not return_description.endswith('>'):
                                             return_description = return_description + '.'
 
                                         output_file.write(f": {return_description}\n")
@@ -1875,8 +1880,9 @@ def write_markdown(type, names, methods):
                                     output_file.write(f"- ({raises_type})")
                                     if "raises_description" in raises_object[raises_type]:
                                         raises_description= raises_object[raises_type]["raises_description"]
-                                        ## Add a trailing period if it is missing:
-                                        if not raises_description.endswith('.'):
+                                        ## Add a trailing period if it is missing, either from upstream or from override file,
+                                        ## but skip doing so if the copy instead ends with an HTML tag (like a closing '</ul>' tag):
+                                        if not raises_description.endswith('.') and not raises_description.endswith('>'):
                                             raises_description = raises_description + '.'
 
                                         output_file.write(f": {raises_description}\n")
@@ -2056,8 +2062,9 @@ def write_markdown(type, names, methods):
 
                                     if param_description:
 
-                                        ## Add a trailing period if it is missing, either from upstream or from override file:
-                                        if not param_description.endswith('.'):
+                                        ## Add a trailing period if it is missing, either from upstream or from override file,
+                                        ## but skip doing so if the copy instead ends with an HTML tag (like a closing '</ul>' tag):
+                                        if not param_description.endswith('.') and not param_description.endswith('>'):
                                             param_description = param_description + '.'
 
                                         output_file.write(f": {param_description}")
@@ -2109,8 +2116,9 @@ def write_markdown(type, names, methods):
 
                                         if return_description:
 
-                                            ## Add a trailing period if it is missing, either from upstream or from override file:
-                                            if not return_description.endswith('.'):
+                                            ## Add a trailing period if it is missing, either from upstream or from override file,
+                                            ## but skip doing so if the copy instead ends with an HTML tag (like a closing '</ul>' tag):
+                                            if not return_description.endswith('.') and not return_description.endswith('>'):
                                                 return_description = return_description + '.'
 
                                             output_file.write(f": {return_description}\n")

docs/appendix/apis/_index.md

@@ -184,13 +184,13 @@ The [generic service](/services/generic/) supports the following methods:
 
 The [ML model service](/services/ml/) supports the following methods:
 
-{{< readfile "/static/include/services/apis/ml.md" >}}
+{{< readfile "/static/include/services/apis/generated/mlmodel-table.md" >}}
 
 ### Motion
 
 The [motion service](/services/motion/) supports the following methods:
 
-{{< readfile "/static/include/services/apis/motion.md" >}}
+{{< readfile "/static/include/services/apis/generated/motion-table.md" >}}
 
 ### Navigation
 

docs/services/ml/deploy/_index.md

@@ -92,7 +92,7 @@ The model package config looks like this:
 
 The MLModel service supports the following methods:
 
-{{< readfile "/static/include/services/apis/ml.md" >}}
+{{< readfile "/static/include/services/apis/generated/mlmodel-table.md" >}}
 
 {{% alert title="Tip" color="tip" %}}
 
@@ -101,202 +101,7 @@ Go to your machine's **CONNECT** tab's **Code sample** page on the [Viam app](ht
 
 {{% /alert %}}
 
-### Infer
-
-Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map.
-
-{{< tabs >}}
-{{% tab name="Python" %}}
-
-**Parameters:**
-
-- `input_tensors` [(Dict[str, NDArray])](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html): A dictionary of input flat tensors, as specified in the metadata.
-- `timeout` [(Optional\[float\])](https://docs.python.org/library/typing.html#typing.Optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
-
-**Returns:**
-
-- [(`Dict[str, NDArray]`)](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html): A dictionary of output flat tensors as specified in the metadata, after being run through an inference engine.
-
-For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.infer).
-
-```python {class="line-numbers linkable-line-numbers"}
-import numpy as np
-
-my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")
-
-nd_array = np.array([1, 2, 3], dtype=np.float64)
-input_tensors = {"0": nd_array}
-
-output_tensors = await my_mlmodel.infer(input_tensors)
-```
-
-{{% /tab %}}
-{{% tab name="Go" %}}
-
-**Parameters:**
-
-- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
-- `tensors` [(ml.Tensors)](https://pkg.go.dev/go.viam.com/[email protected]/ml#Tensors): The input map of tensors, as specified in the metadata.
-
-**Returns:**
-
-- [(ml.Tensors)](https://pkg.go.dev/go.viam.com/[email protected]/ml#Tensors): The output map of tensors, as specified in the metadata, after being run through an inference engine.
-- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
-
-For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/mlmodel#Service).
-
-```go {class="line-numbers linkable-line-numbers"}
-input_tensors := ml.Tensors{"0": tensor.New(tensor.WithShape(1, 2, 3), tensor.WithBacking(6))}
-
-output_tensors, err := myMLModel.Infer(context.Background(), input_tensors)
-```
-
-{{% /tab %}}
-{{< /tabs >}}
-
-### Metadata
-
-Get the metadata: name, data type, expected tensor/array shape, inputs, and outputs associated with the ML model.
-
-{{< tabs >}}
-{{% tab name="Python" %}}
-
-**Parameters:**
-
-- `timeout` [(Optional\[float\])](https://docs.python.org/library/typing.html#typing.Optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
-
-**Returns:**
-
-- [(`Metadata`)](https://python.viam.dev/autoapi/viam/gen/service/mlmodel/v1/mlmodel_pb2/index.html#viam.gen.service.mlmodel.v1.mlmodel_pb2.Metadata): Name, type, expected tensor/array shape, inputs, and outputs associated with the ML model.
-
-For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.metadata).
-
-```python {class="line-numbers linkable-line-numbers"}
-my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")
-
-metadata = await my_mlmodel.metadata()
-```
-
-{{% /tab %}}
-{{% tab name="Go" %}}
-
-**Parameters:**
-
-- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
-
-**Returns:**
-
-- [(MLMetadata)](https://pkg.go.dev/go.viam.com/[email protected]/services/mlmodel#MLMetadata): Struct containing the metadata of the model file, such as the name of the model, what kind of model it is, and the expected tensor/array shape and types of the inputs and outputs of the model.
-- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
-
-For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/mlmodel#Service).
-
-```go {class="line-numbers linkable-line-numbers"}
-metadata, err := myMLModel.Metadata(context.Background())
-```
-
-{{% /tab %}}
-{{< /tabs >}}
-
-### DoCommand
-
-Execute model-specific commands that are not otherwise defined by the service API.
-For built-in service models, any model-specific commands available are covered with each model's documentation.
-If you are implementing your own navigation service and add features that have no built-in API method, you can access them with `DoCommand`.
-
-{{< tabs >}}
-{{% tab name="Python" %}}
-
-**Parameters:**
-
-- `command` [(Mapping[str, ValueTypes])](https://docs.python.org/3/library/stdtypes.html#typesmapping): The command to execute.
-- `timeout` [(Optional\[float\])](https://docs.python.org/library/typing.html#typing.Optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
-
-**Returns:**
-
-- [(Mapping[str, ValueTypes])](https://docs.python.org/3/library/stdtypes.html#typesmapping): Result of the executed command.
-
-**Raises:**
-
-- `NotImplementedError`: Raised if the Resource does not support arbitrary commands.
-
-```python {class="line-numbers linkable-line-numbers"}
-my_mlmodel = MLModelClient.from_robot(robot=robot, name="my_mlmodel_service")
-
-my_command = {
-  "command": "dosomething",
-  "someparameter": 52
-}
-
-await my_mlmodel.do_command(my_command)
-```
-
-For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.do_command).
-
-{{% /tab %}}
-{{% tab name="Go" %}}
-
-**Parameters:**
-
-- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
-- `cmd` [(map\[string\]interface{})](https://go.dev/blog/maps): The command to execute.
-
-**Returns:**
-
-- [(map\[string\]interface{})](https://go.dev/blog/maps): Result of the executed command.
-- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
-
-```go {class="line-numbers linkable-line-numbers"}
-resp, err := myMLModel.DoCommand(context.Background(), map[string]interface{}{"command": "dosomething", "someparameter": 52})
-```
-
-For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).
-
-{{% /tab %}}
-{{< /tabs >}}
-
-### Close
-
-Safely shut down the resource and prevent further use.
-
-{{< tabs >}}
-{{% tab name="Python" %}}
-
-**Parameters:**
-
-- None
-
-**Returns:**
-
-- None
-
-```python {class="line-numbers linkable-line-numbers"}
-my_mlmodel = MLModelClient.from_robot(robot, "my_mlmodel_service")
-
-await my_mlmodel.close()
-```
-
-For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/mlmodel/client/index.html#viam.services.mlmodel.client.MLModelClient.close).
-
-{{% /tab %}}
-{{% tab name="Go" %}}
-
-**Parameters:**
-
-- `ctx` [(Context)](https://pkg.go.dev/context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
-
-**Returns:**
-
-- [(error)](https://pkg.go.dev/builtin#error) : An error, if one occurred.
-
-```go {class="line-numbers linkable-line-numbers"}
-err := myMLModel.Close(context.Background())
-```
-
-For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).
-
-{{% /tab %}}
-{{< /tabs >}}
+{{< readfile "/static/include/services/apis/generated/mlmodel.md" >}}
 
 ## Use the ML model service with the Viam Python SDK