Merge pull request #2408 from reubenmiller/docs-enforce-te2mqtt-v1-format

docs: enforce/normalize v1 format on all te2mqtt code blocks

Author: reubenmiller

docs/src/contribute/design/mqtt-topic-design.md

@@ -16,13 +16,13 @@ Having a fixed **identifier** group in the topic structure makes it easier for o
 
 A client can subscribe to all measurements for the main device by subscribing to a single topic.
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/device/main///m/+'
 ```
 
 Alternatively, if a client wants to subscribe to all measurements regardless of the **identifier** then it can also can be done using a single subscription, as demonstrated by the following example:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/+/+/+/+/m/+'
 ```
 
@@ -119,7 +119,7 @@ graph LR
 
 The equipment, which is a conveyor belt called "belt01", is located in factory "factory01", in the "hallA" building, in the "packaging" area. The conveyor belt can be registered as a child-device by publishing the following message.
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub -r 'te/factory01/hallA/packaging/belt001' '{
   "@type": "child-device",
   "name": "belt001",
@@ -139,15 +139,15 @@ The registration message will associate the telemetry data or commands published
 
 For example, an event can be published to the `belt01` equipment using the following message.
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub 'te/factory01/hallA/packaging/belt001/e/running_status' '{
   "text": "Belt started"
 }'
 ```
 
 Since the topic schema encodes additional location information about the equipment, other MQTT clients can subscribe to telemetry data coming from all equipment located in the same area using a single MQTT subscription.
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub 'te/factory01/hallA/packaging/+/e/+'
 ```
 
@@ -156,15 +156,15 @@ When applying your own semantics to the **identifier**, you can leave any segmen
 
 For example, if it does not make sense to have the factory and building in the **identifier**, then they can be removed and the equipment can be registered using:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub -r 'te/packaging/belt001' '{
   "@type": "child-device"
 }'
 ```
 
 Publishing an event requires just leaving the last two segments of the **identifier** blank (whilst keeping the slashes `/` in place).
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub 'te/packaging/belt001///e/running_status' '{
   "text": "Belt started"
 }'

docs/src/contribute/writing-documentation/markdown-components.md

@@ -210,14 +210,14 @@ The following shows how to document how to publish a single MQTT message.
 **Markdown**
 
 ````markdown title="Markdown"
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt pub te/device/main///m/ '{"temperature": 21.3}'
 ```
 ````
 
 **Output**
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt pub te/device/main///m/ '{"temperature": 21.3}'
 ```
 
@@ -296,14 +296,14 @@ tedge mqtt pub te/device/child01///a/temp_hi_hi '{"text": "Temperature Hi Hi", "
 ### Example: Subscribe to MQTT messages
 
 ````markdown title="Markdown"
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/#'
 ```
 ````
 
 **Output**
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/#'
 ```
 
@@ -312,14 +312,14 @@ tedge mqtt sub 'te/#'
 Any additional arguments will be automatically preserved when translating the commands. Though the `mqtt` tab will not display this information it is just meant to represent the MQTT message and does not know anything about the terminal/console.
 
 ````markdown title="Markdown"
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/#' > logged.tedge.messages.txt
 ```
 ````
 
 **Output**
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/#' > logged.tedge.messages.txt
 ```
 

docs/src/operate/c8y/child_device_config_management_agent.md

@@ -75,7 +75,7 @@ to the URL: `http://{tedge-ip}:8000/tedge/file-transfer/{child-id}/c8y-configura
 
 Once the upload is complete, the agent should notify thin-edge about the upload by sending the following MQTT message:
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt pub 'tedge/{child-d}/commands/res/config_snapshot' '{"type": "c8y-configuration-plugin", "path": "/child/local/fs/path"}'
 ```
 
@@ -107,7 +107,7 @@ The `url` value is what the child device agent must use to upload the requested
 
 On receipt of the request, the agent must send an "executing" MQTT status message as follows:
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt pub tedge/{child-d}/commands/res/config_snapshot '{
   "status": "executing",
   "type": "{config-type}",

docs/src/operate/c8y/retrieve_jwt_token_from_cumulocity.md

@@ -17,13 +17,13 @@ Follow the below steps in order to retrieve the token from the Cumulocity cloud
 
 1. Subscribe to token topic
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=v1
     tedge mqtt sub c8y/s/dat --no-topic
     ```
 
 2. Publish an empty message on `c8y/s/uat` topic
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=v1
     tedge mqtt pub c8y/s/uat ''
     ```
 

docs/src/operate/configuration/child-device-config-management.md

@@ -188,7 +188,7 @@ Follow these steps to bootstrap the child device:
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt pub "tedge/child1/commands/res/config_snapshot" '{"path": "", "type":"c8y-configuration-plugin"}'
     ```
 
@@ -202,7 +202,7 @@ Following these steps, a configuration file from the child-device will be reques
 
 1. Subscribe to config snapshot requests via MQTT
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt sub "tedge/{child-id}/commands/req/config_snapshot"
     ```
 
@@ -249,7 +249,7 @@ Following these steps, a configuration file from the child-device will be reques
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt pub "tedge/child1/commands/res/config_snapshot" '{"status": "executing", "path": "/home/pi/config/config1", "type": "config1"}'
     ```
 
@@ -289,7 +289,7 @@ Following these steps, a configuration file from the child-device will be reques
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt pub "tedge/child1/commands/res/config_snapshot" '{"status": "successful", "path": "/home/pi/config/config1", "type": "config1"}'
     ```
 
@@ -301,7 +301,7 @@ Performing config update is an 8-step process:
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt sub "tedge/child1/commands/req/config_update"
     ```
 
@@ -352,7 +352,7 @@ Performing config update is an 8-step process:
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt pub "tedge/child1/commands/res/config_update" '{"status": "executing", "path": "/home/pi/config/config1", "type": "config1"}'
     ```
 
@@ -398,7 +398,7 @@ Performing config update is an 8-step process:
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt pub "tedge/child1/commands/res/config_update" '{"status": "successful", "path": "/home/pi/config/config1", "type": "config1"}'
     ```
 
@@ -415,7 +415,7 @@ Performing config update is an 8-step process:
 
     **Example**
 
-    ```sh te2mqtt
+    ```sh te2mqtt formats=legacy
     tedge mqtt pub "tedge/child1/commands/res/config_update" '{"status": "failed", "reason": "Download failed", "path": "/home/pi/config/config1", "type": "config1"}'
     ```
 

docs/src/operate/monitoring/enable_tedge_watchdog_using_systemd.md

@@ -84,11 +84,11 @@ One can observe the message exchange between the `service` and the `watchdog`
 by subscribing to the following topics:
 
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/+/+/+/+/status/health'
 ```
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/+/+/+/+/cmd/health/check'
 ```
 

docs/src/operate/telemetry/pub_sub.md

@@ -14,21 +14,21 @@ Command [`tedge mqtt pub`](../../references/cli/tedge-mqtt.md) can be used to pu
 
 Example:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub 'te/device/main///m/env_sensor' '{"temperature": 21.3}'
 ```
 
 Messages can also be published with a different Quality of Service (QoS).
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub 'te/device/main///m/env_sensor' '{"temperature": 21.3}' --qos 2
 ```
 
 MQTT messages can also be published using the retained option which means that the message will be received by new MQTT clients connecting to the broker after the message was published.
 
 Below shows an example of publishing a retained MQTT message:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain --qos 1 te/device/main///a/high_temperature '{
     "text": "Temperature is critical",
     "severity": "critical"
@@ -44,25 +44,25 @@ By default the mqtt message will be published with retain flag set to false.
 
 Command [`tedge mqtt sub`](../../references/cli/tedge-mqtt.md) can be used to ease debugging of of MQTT communication on local bridge. You can subscribe to topic of your choosing:
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub te/errors
 ```
 
 Or you can subscribe to any topic on the server using wildcard (`#`) topic:
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub '#'
 ```
 
 Now using a different console/shell, publish the following measurement so that the previous subscription will receive it:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain --qos 1 te/device/main///m/env_sensor '{"temperature": 21.3}'
 ```
 
 All messages from sub command are printed to `stdout` and can be captured to a file if you need to:
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub '#' > filename.mqtt
 ```
 

docs/src/operate/troubleshooting/monitor_tedge_health.md

@@ -45,7 +45,7 @@ and this will be retained until the service is restarted.
 
 E.g. the mapper being killed:
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/+/+/+/+/status/health'
 ```
 

docs/src/operate/troubleshooting/trouble_shooting_monitoring.md

@@ -23,7 +23,7 @@ sudo systemctl start collectd
 
 ## Is collectd publishing MQTT messages?
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'collectd/#'
 ```
 
@@ -47,21 +47,21 @@ sudo systemctl start tedge-mapper-collectd
 
 ## Are the collectd metrics published in Thin Edge JSON format?
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/device/main///m/+'
 ```
 
 ## Are the collectd metrics published to Cumulocity IoT?
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'c8y/#'
 ```
 
 If not see how to [connect a device to Cumulocity IoT](../../start/connect-c8y.md).
 
 ## Are the collectd metrics published to Azure IoT?
 
-```sh te2mqtt
+```sh te2mqtt formats=v1
 tedge mqtt sub 'az/#'
 ```
 

docs/src/references/agent/device-management-api.md

@@ -66,7 +66,7 @@ that this device can be sent commands of this type.
 These messages are published with the retained flag set. So, a client process, such a mapper, can discover on start
 what are __all the capabilities of all the devices__:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/+/+/+/+/cmd/+'
 ```
 
@@ -105,7 +105,7 @@ It is recommended to either use a unique id generator, or add a unix timestamp a
 The messages published on these topics represent each the current status of a running command.
 So, one can list __all the in-progress commands of any type across all the devices__:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt sub 'te/+/+/+/+/cmd/+/+'
 ```
 
@@ -222,7 +222,7 @@ As an example, let's take software updates on a child device.
 When launched on the child device `device/child001//`,
 `tedge-agent` notifies that software packages of types: `apt` and `docker` can be updated on this device:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain 'te/device/child001///cmd/software_update' '{
     "description": "Install, update and remove software packages",
     "types": [
@@ -235,7 +235,7 @@ tedge mqtt pub --retain 'te/device/child001///cmd/software_update' '{
 On reception of this message, the Cumulocity mapper notifies Cumulocity of this capability.
 On request from a cloud operator, the Cumulocity mapper creates a new command instance, say to update `nodered`:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain 'te/device/child001///cmd/software_update/c8y-123' '{
     "status": "init",
     "updateList": [
@@ -255,7 +255,7 @@ tedge mqtt pub --retain 'te/device/child001///cmd/software_update/c8y-123' '{
 
 The agent, running on `device/child001//`, notifies that it will execute the command:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain 'te/device/child001///cmd/software_update/c8y-123' '{
     "status": "executing",
     "updateList": [
@@ -275,7 +275,7 @@ tedge mqtt pub --retain 'te/device/child001///cmd/software_update/c8y-123' '{
 
 Then the agent proceeds, here installing a specific version of `nodered`, and notifies the mapper when done:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain 'te/device/child001///cmd/software_update/c8y-123' '{
     "status": "successful",
     "updateList": [
@@ -297,6 +297,6 @@ The Cumulocity mapper, having subscribed to all software_update commands,
 monitors this command instance and notifies Cumulocity of its progress upto completion.  
 Finally, the Cumulocity mapper clear the command topic:
 
-```sh te2mqtt formats="v1"
+```sh te2mqtt formats=v1
 tedge mqtt pub --retain 'te/device/child001///cmd/software_update/c8y-123' ''
 ```