Fix python formatting everywhere (#1837)

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+extend-ignore = F704, F821, F401, F841
+exclude = .git,build,dist
+max-complexity = 20

.github/workflows/python-lint.yml

@@ -0,0 +1,19 @@
+name: Lint Python Code Snippets
+
+on:
+  workflow_dispatch:
+  pull_request:
+
+jobs:
+  python_lint:
+    name: Check Python snippets in Markdown files
+    continue-on-error: true
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install Flake8 Markdown linter
+        run: pip3 install flake8-markdown
+
+      - name: Markdown Lint
+        run: flake8-markdown "docs/**/*.md"

README.md

@@ -43,6 +43,12 @@ python3 -m http.server 9000 --directory public
 
 ## Test the docs locally
 
+To ensure all python snippets are properly formatted before creating a commit, install [flake8-markdown](https://github.com/johnfraney/flake8-markdown) and add the following like to `.git/hooks/pre-commit`:
+
+```sh
+flake8-markdown  $(git diff --diff-filter=d --name-only HEAD | grep '\.md$')
+```
+
 To ensure your markdown is properly formatted, run `make markdowntest`.
 
 To check for broken links run `make htmltest`.

docs/components/arm/_index.md

@@ -257,14 +257,16 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/_modules
 ```python {class="line-numbers linkable-line-numbers"}
 my_arm = Arm.from_robot(robot=robot, name="my_arm")
 
-# Declare a list of values with your desired rotational value for each joint on the arm.
+# Declare a list of values with your desired rotational value for each joint on
+# the arm.
 degrees = [0.0, 45.0, 0.0, 0.0, 0.0]
 
 # Declare a new JointPositions with these values.
-jointPos = arm.move_to_joint_positions(JointPositions(values=[0.0, 45.0, 0.0, 0.0, 0.0]))
+jointPos = arm.move_to_joint_positions(
+    JointPositions(values=[0.0, 45.0, 0.0, 0.0, 0.0]))
 
 # Move each joint of the arm to the position these values specify.
-await my_arm.move_to_joint_positions(positions= jointPos)
+await my_arm.move_to_joint_positions(positions=jointPos)
 ```
 
 {{% /tab %}}
@@ -425,14 +427,13 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 my_arm = Arm.from_robot(robot=robot, name="my_arm")
 
 # Get the kinematics information associated with the arm.
-kinematics := await my_arm.get_kinematics()
+kinematics = await my_arm.get_kinematics()
 
 # Get the format of the kinematics file.
 k_file = kinematics[0]
 
 # Get the byte contents of the file.
 k_bytes = kinematics[1]
-
 ```
 
 {{% /tab %}}

docs/components/base/_index.md

@@ -225,19 +225,27 @@ my_base = Base.from_robot(robot=robot, name="my_base")
 
 # Make your wheeled base move forward. Set linear power to 75%.
 print("move forward")
-await my_base.set_power(linear=Vector3(x=0,y=-.75,z=0), angular=Vector3(x=0,y=0,z=0))
+await my_base.set_power(
+    linear=Vector3(x=0, y=-.75, z=0),
+    angular=Vector3(x=0, y=0, z=0))
 
 # Make your wheeled base move backward. Set linear power to -100%.
 print("move backward")
-await my_base.set_power(linear=Vector3(x=0,y=-1.0,z=0), angular=Vector3(x=0,y=0,z=0))
+await my_base.set_power(
+    linear=Vector3(x=0, y=-1.0, z=0),
+    angular=Vector3(x=0, y=0, z=0))
 
 # Make your wheeled base spin left. Set angular power to 100%.
 print("spin left")
-await my_base.set_power(linear=Vector3(x=0,y=0,z=0), angular=Vector3(x=0,y=0,z=1))
+await my_base.set_power(
+    linear=Vector3(x=0, y=0, z=0),
+    angular=Vector3(x=0, y=0, z=1))
 
 # Make your wheeled base spin right. Set angular power to -75%.
 print("spin right")
-await my_base.set_power(linear=Vector3(x=0,y=0,z=0), angular=Vector3(x=0,y=0,z=-.75))
+await my_base.set_power(
+    linear=Vector3(x=0, y=0, z=0),
+    angular=Vector3(x=0, y=0, z=-.75))
 ```
 
 {{% /tab %}}
@@ -309,8 +317,10 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 ```python {class="line-numbers linkable-line-numbers"}
 my_base = Base.from_robot(robot=robot, name="my_base")
 
-# Set the linear velocity to 50 mm/sec and the angular velocity to 15 degree/sec.
-await my_base.set_velocity(linear=Vector3(x=0,y=50,z=0), angular=Vector3(x=0,y=0,z=15))
+# Set the linear velocity to 50 mm/sec and the angular velocity to
+# 15 degree/sec.
+await my_base.set_velocity(
+    linear=Vector3(x=0, y=50, z=0), angular=Vector3(x=0, y=0, z=15))
 ```
 
 {{% /tab %}}
@@ -469,10 +479,10 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 ```python {class="line-numbers linkable-line-numbers"}
 my_base = Base.from_robot(robot=robot, name="my_base")
 
-# Get the width and turning radius of the base 
+# Get the width and turning radius of the base
 properties = await my_base.get_properties()
 
-# Get the width 
+# Get the width
 print(f"Width of base in meters: {properties.width}")
 
 # Get the turning radius
@@ -497,7 +507,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c
 ```go {class="line-numbers linkable-line-numbers"}
 myBase, err := base.FromRobot(robot, "my_base")
 
-// Get the width and turning radius of the base 
+// Get the width and turning radius of the base
 properties, err := myBase.Properties(context.Background(), nil)
 
 // Get the width

docs/components/board/_index.md

@@ -448,10 +448,11 @@ Get an [`DigitalInterrupt`](#digital_interrupts) by `name.`
 For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/index.html#viam.components.board.Board.digital_interrupt_by_name).
 
 ```python
-my_board = Board.from_robot(robot=robot, name=)
+my_board = Board.from_robot(robot=robot, name="my_board")
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 ```
 
 {{% /tab %}}
@@ -1047,7 +1048,8 @@ my_board = Board.from_robot(robot=robot, name="my_board")
 # Get the GPIOPin with pin number 15.
 pin = await my_board.GPIO_pin_by_name(name="15")
 
-# Set the duty cycle to .6, meaning that this pin will be in the high state for 60% of the duration of the PWM interval period.
+# Set the duty cycle to .6, meaning that this pin will be in the high state for
+# 60% of the duration of the PWM interval period.
 await pin.set_pwm(cycle=.6)
 ```
 
@@ -1225,9 +1227,11 @@ pin = await my_board.GPIO_pin_by_name(name="15")
 duty_cycle = await pin.get_pwm()
 
 # Get the AnalogReader "my_example_analog_reader".
-reader = await my_board.analog_reader_by_name(name="my_example_analog_reader")
+reader = await my_board.analog_reader_by_name(
+    name="my_example_analog_reader")
 
-# Get the value of the digital signal "my_example_analog_reader" has most recently measured.
+# Get the value of the digital signal "my_example_analog_reader" has most
+# recently measured.
 reading = reader.read()
 ```
 
@@ -1288,9 +1292,11 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 my_board = Board.from_robot(robot=robot, name="my_board")
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 
-# Get the amount of times this DigitalInterrupt has been interrupted with a tick.
+# Get the amount of times this DigitalInterrupt has been interrupted with a
+# tick.
 count = await interrupt.value()
 ```
 
@@ -1341,9 +1347,11 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 my_board = Board.from_robot(robot=robot, name="my_board")
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 
-# Get the rolling average of the pulse width across each time the DigitalInterrupt is interrupted with a tick.
+# Get the rolling average of the pulse width across each time the
+# DigitalInterrupt is interrupted with a tick.
 rolling_avg = await interrupt.value()
 ```
 
@@ -1407,7 +1415,8 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 my_board = Board.from_robot(robot=robot, name="my_board")
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 
 # Record an interrupt and notify any interested callbacks.
 await interrupt.tick(high=true, nanos=12345)
@@ -1431,7 +1440,8 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 my_board = Board.from_robot(robot=robot, name="my_board")
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 
 # Record an interrupt and notify any interested callbacks.
 await interrupt.tick(high=true, nanos=12345)
@@ -1524,7 +1534,8 @@ pin = await my_board.GPIO_pin_by_name(name="15")
 callback_queue = Queue(maxsize=10)
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 
 # Add a queue to the interrupt.
 interrupt.add_callback(callback_queue)
@@ -1618,7 +1629,8 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 my_board = Board.from_robot(robot=robot, name="my_board")
 
 # Get the DigitalInterrupt "my_example_digital_interrupt".
-interrupt = await my_board.digital_interrupt_by_name(name="my_example_digital_interrupt")
+interrupt = await my_board.digital_interrupt_by_name(
+    name="my_example_digital_interrupt")
 ```
 ``` -->
 

docs/components/camera/_index.md

@@ -133,7 +133,7 @@ frame = await my_cam.get_image()
 
 # Convert "frame" to a standard 2D image representation.
 # Remove the 1st 3x8 bytes and reshape the raw bytes to List[List[Int]].
-standard_frame frame.bytes_to_depth_array()
+standard_frame = frame.bytes_to_depth_array()
 ```
 
 {{% alert title="Tip" color="tip" %}}
@@ -253,7 +253,7 @@ To deserialize the returned information into a numpy array, use the Open3D libra
 import numpy as np
 import open3d as o3d
 
-my_camera= Camera.from_robot(robot=robot, name="my_camera")
+my_camera = Camera.from_robot(robot=robot, name="my_camera")
 
 data, _ = await my_camera.get_point_cloud()
 
@@ -306,7 +306,7 @@ Get the camera intrinsic parameters and camera distortion, as well as whether th
 - [(Properties)](https://python.viam.dev/autoapi/viam/components/camera/index.html#viam.components.camera.Camera.Properties): The properties of the camera.
 
 ```python {class="line-numbers linkable-line-numbers"}
-my_camera= Camera.from_robot(robot=robot, name="my_camera")
+my_camera = Camera.from_robot(robot=robot, name="my_camera")
 
 properties = await my_camera.get_properties()
 ```
@@ -356,7 +356,7 @@ If you are implementing your own camera and adding features that have no native
 - [(Dict[str, Any])](https://docs.python.org/3/library/stdtypes.html#typesmapping): Result of the executed command.
 
 ```python {class="line-numbers linkable-line-numbers"}
-my_camera= Camera.from_robot(robot, "my_camera")
+my_camera = Camera.from_robot(robot, "my_camera")
 
 command = {"cmd": "test", "data1": 500}
 result = my_camera.do(command)

docs/components/gantry/_index.md

@@ -156,13 +156,15 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/_modules
 ```python
 my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
 
-# Create a list of positions for the axes of the gantry to move to. Assume in this example that the gantry is multi-axis, with 3 axes.
+# Create a list of positions for the axes of the gantry to move to. Assume in
+# this example that the gantry is multi-axis, with 3 axes.
 examplePositions = [1, 2, 3]
 
 exampleSpeeds = [3, 9, 12]
 
 # Move the axes of the gantry to the positions specified.
-await my_gantry.move_to_position(positions=examplePositions, speeds=exampleSpeeds)
+await my_gantry.move_to_position(
+    positions=examplePositions, speeds=exampleSpeeds)
 ```
 
 {{% /tab %}}
@@ -315,7 +317,8 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/_modules
 ```python
 my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
 
-# Stop all motion of the gantry. It is assumed that the gantry stops immediately.
+# Stop all motion of the gantry. It is assumed that the gantry stops
+# immediately.
 await my_gantry.stop()
 ```
 
@@ -363,7 +366,8 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/_modules
 ```python
 my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")
 
-# Stop all motion of the gantry. It is assumed that the gantry stops immediately.
+# Stop all motion of the gantry. It is assumed that the
+# gantry stops immediately.
 await my_gantry.stop()
 
 # Print if the gantry is currently moving.