Create linkcheck.yml (viamrobotics#655)

Author: npentrel

.github/workflows/linkcheck.yml

@@ -0,0 +1,47 @@
+# .github/workflows/run-htmltest.yml
+# (c) 2021 Robb Romans
+#
+# Run htmltest link checker on generated HTML output in dist/
+# https://github.com/wjdp/htmltest
+#
+name: run-htmltest-external
+concurrency:
+  group: pullrequest-untrusted-htmltest-${{ github.event.number }}
+  cancel-in-progress: true
+on: pull_request
+jobs:
+  htmltest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+
+      - name: Install package
+        run: make install
+
+      - name: Generate docs
+        run: |
+          make documentation
+
+      - name: Test HTML
+        # https://github.com/wjdp/htmltest-action/
+        # Don't fail the build on broken links
+        continue-on-error: false
+        uses: wjdp/htmltest-action@master
+        with:
+          config: .htmltest.yml
+      - name: Archive htmltest results
+        uses: actions/upload-artifact@v3
+        # Note: Set ACTIONS_RUNTIME_TOKEN env variable to test with nektos/act
+        with:
+          name: htmltest-report
+          path: tmp/.htmltest/htmltest.log
+          retention-days: 7 # Default is 90 days

.htmltest.yml

@@ -0,0 +1,17 @@
+DirectoryPath: "docs/_build/html"
+EnforceHTTPS: true
+IgnoreEmptyHref: true
+IgnoreInternalEmptyHash: true
+IgnoreDirectoryMissingTrailingSlash: false
+IgnoreURLs:
+  - "app.viam.com"
+  - "fonts.gstatic.com"
+  - "contributor-covenant.org"
+IgnoreDirs:
+  - "lib"
+CacheExpires: "6h"
+# IgnoreDirs: - if we need to ever ignore files
+CheckInternal: false
+CheckDoctype: false
+CheckScripts: false
+FileExtension: ".html"

README.md

@@ -100,7 +100,7 @@ Sessions are a safety feature that automatically cancel operations made by the p
 Read the [Example Usage](https://python.viam.dev/examples/example.html) page, to learn how to access a component, build a custom component, and expose
 custom components as a remote to existing robots.
 
-More examples can be found in the [`examples`](/examples) directory.
+More examples can be found in the [`examples`](https://github.com/viamrobotics/viam-python-sdk/tree/main/examples) directory.
 
 ## Documentation
 

docs/examples/example.ipynb

@@ -317,7 +317,7 @@
     "### 2. Register the new modular resource\n",
     "Now that we've created the modular resource model, we must register it to the registry.\n",
     "\n",
-    "Define a [`Model`](https://docs.viam.com/extend/modular-resources/#models) name and a creator function in the resource. A creator function is a function that can create a resource given a config and map of dependencies.\n",
+    "Define a [`Model`](https://docs.viam.com/appendix/glossary/#term-model) name and a creator function in the resource. A creator function is a function that can create a resource given a config and map of dependencies.\n",
     "\n",
     "To define a creator function and `Model` in `wifi_sensor_module.py`, import `ComponentConfig`, `ResourceName`, `ResourceBase`, `Model`, and `ModelFamily` from the relative viam packages. Please note that the import packages also have to be changed to include `Mapping` and `ClassVar` from `typing` and `Self` from `typing_extensions`. The changes can be seen in the example below.\n",
     "\n",
@@ -533,7 +533,7 @@
     "\n",
     "[Configure your new module](https://docs.viam.com/extend/modular-resources/#configure-your-module) on your robot by navigating to the **Config** tab of the robot's page on the Viam app, then click on the **Modules** subtab. Add the name of your module and the executable path. For our example, the path would be `<path-on-your-filesystem>/linux-wifi/run.sh`.\n",
     "\n",
-    "Once you have configured a module as part of your robot configuration, [configure your modular resource](https://docs.viam.com/extend/modular-resources/#configure-your-modular-resource) made available by that module by adding new components or services configured with your modular resources' new type or model. To instantiate a new resource from your module, specify the `type`, `model`, and `name` of your modular resource. The aforementioned `type`, `model`, and `name` should be the same as those in the `MODEL` class attribute defined in your [component class](#2-register-the-custom-component). This is a JSON example:\n",
+    "Once you have configured a module as part of your robot configuration, [configure your modular resource](https://docs.viam.com/extend/modular-resources/#configure-your-modular-resource) made available by that module by adding new components or services configured with your modular resources' new type or model. To instantiate a new resource from your module, specify the `type`, `model`, and `name` of your modular resource. The aforementioned `type`, `model`, and `name` should be the same as those in the `MODEL` class attribute defined in your [component class](#register-the-custom-component). This is a JSON example:\n",
     "\n",
     "```json\n",
     "{\n",
@@ -555,7 +555,7 @@
     "}\n",
     "```\n",
     "\n",
-    "Note the nomenclature of the above `model` field, `viam:sensor:linux-wifi`. Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/extend/modular-resources/key-concepts/#models).\n",
+    "Note the nomenclature of the above `model` field, `viam:sensor:linux-wifi`. Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/registry/create/#name-your-new-resource-model).\n",
     "\n",
     "Viam also provides many built-in models that implement API capabilities, each using `rdk` as the `namespace`, and `builtin` as the `family`:\n",
     "- The `rdk:builtin:gpio` model of the `rdk:component:motor` API provides RDK support for [GPIO-controlled DC motors](https://docs.viam.com/components/motor/gpio/).\n",
@@ -570,7 +570,7 @@
     "### Custom Modular Arm Example\n",
     "The following is an example of how to implement a custom modular arm. For further instructions, read the detailed `Sensor` example above. Our custom Arm will be extremely simple. Please note that the minimum set of endpoints you need to implement for an arm are `GetKinematics`, `GetJointPositions`, and `MoveToJointPositions`.\n",
     "\n",
-    "This arm example contains a minimal kinematics model. For a full model, take a look [here](https://github.com/viamrobotics/viam-python-sdk/blob/main/complex_module/src/arm/my_arm_kinematics.json).\n",
+    "This arm example contains a minimal kinematics model. For a full model, take a look [here](https://github.com/viamrobotics/viam-python-sdk/blob/main/examples/complex_module/src/arm/my_arm_kinematics.json).\n",
     "\n",
     "Subclassing the `Arm` component and implementing the required functions:\n",
     "```python\n",
@@ -908,7 +908,7 @@
    "source": [
     "You can view more component implementations in the [examples](https://github.com/viamrobotics/python-sdk/blob/main/examples/server/v1/components.py).\n",
     "\n",
-    "This arm example contains a minimal kinematics model. For a full model, take a look [here](https://github.com/viamrobotics/viam-python-sdk/blob/main/complex_module/src/arm/my_arm_kinematics.json)."
+    "This arm example contains a minimal kinematics model. For a full model, take a look [here](https://github.com/viamrobotics/viam-python-sdk/blob/main/examples/complex_module/src/arm/my_arm_kinematics.json)."
    ]
   },
   {

examples/complex_module/README.md

@@ -38,7 +38,7 @@ The `run.sh` script is the entrypoint for this module. To connect this module wi
 
 Once the module has been added to your robot, add a `Gizmo` component that uses the `MyGizmo` model. See the [documentation](https://docs.viam.com/extend/modular-resources/configure/) for more details. You can also add an `Arm` component that uses the `MyArm` model and a `Summation` service that uses the `MySum` model in a similar manner.
 
-Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/extend/modular-resources/key-concepts/#models).
+Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/registry/create/#name-your-new-resource-model).
 
 An example configuration for an Arm component, a Gizmo component, and a Summation service could look like this:
 

examples/simple_module/README.md

@@ -28,7 +28,7 @@ The `run.sh` script is the entrypoint for this module. To connect this module wi
 
 Once the module has been added to your robot, add a new component that uses the `MySensor` model. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#configure-a-component-instance-for-a-modular-resource) for more details.
 
-Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/extend/modular-resources/key-concepts/#models).
+Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/registry/create/#name-your-new-resource-model).
 
 An example configuration for a Sensor component could look like this:
 ```json

src/viam/app/data_client.py

@@ -1018,7 +1018,7 @@ async def binary_data_capture_upload(
                 or .png extension will be saved to the images tab.
             method_parameters (Optional[Mapping[str, Any]]): Optional dictionary of method parameters. No longer in active use.
             tags (Optional[List[str]]): Optional list of tags to allow for tag-based data filtering when retrieving data.
-            data_request_times (Optional[Tuple[datetime.datetime, datetime.datetime]]): Optional tuple containing `datetime`s objects
+            data_request_times (Optional[Tuple[datetime.datetime, datetime.datetime]]): Optional tuple containing datetime objects
                 denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.
 
         Raises:
@@ -1184,7 +1184,7 @@ async def streaming_data_capture_upload(
             component_name (Optional[str]): Optional name of the component associated with the file.
             method_name (Optional[str]): Optional name of the method associated with the file.
             method_parameters (Optional[str]): Optional dictionary of the method parameters. No longer in active use.
-            data_request_times (Optional[Tuple[datetime.datetime, datetime.datetime]]): Optional tuple containing `datetime`s objects
+            data_request_times (Optional[Tuple[datetime.datetime, datetime.datetime]]): Optional tuple containing datetime objects
                 denoting the times this data was requested[0] by the robot and received[1] from the appropriate sensor.
             tags (Optional[List[str]]): Optional list of tags to allow for tag-based filtering when retrieving data.
 

src/viam/resource/easy_resource.py

@@ -32,11 +32,13 @@ class EasyResource:
 
     Basic usage:
 
-    class MyModel(Sensor, EasyResource):
-        MODEL = "my-org:sensor:my-sensor"
+    ::
 
-        async def get_readings(self, **kwargs):
-            return {"ok": True}
+        class MyModel(Sensor, EasyResource):
+            MODEL = "my-org:sensor:my-sensor"
+
+            async def get_readings(self, **kwargs):
+                return {"ok": True}
 
     See examples/easy_resource/main.py for extended usage.
     """