Working on documentation

davisconditions.py

@@ -1,11 +1,68 @@
-#!/usr/home/homeassistant/bin/python3
+#!/usr/bin/env python3
 #
-# Gather data from the Davis WeatherLink Live and output it
+# Description:
+#
+# Gathers data from the Davis WeatherLink Live and outputs it
 # in JSON format for use in Home Assistant.
 # Designed to be run as a command_line integration.
 #
-# Requires Python3 and the requests package.
-# Update the first line to the python3 binary used by HomeAssistant.
+# Requirements:
+# - Python 3.9+
+# - requests package
+# - Update the first line to the python3 binary used by HomeAssistant.
+#
+# Usage/installation:
+#
+# Takes a single argument: the 8-digit code identifying the station.
+# This is part of the URL you'd use to view the information on the web,
+# and is listed on the web page. For example,
+# https://waterdata.usgs.gov/monitoring-location/14339000/
+# is for measurement station 14339000.
+# The web page title is:
+# Rogue River at Dodge Bridge, Near Eagle Point, OR - 14339000
+# This means that the command line would be:
+# /path/to/binary/riverconditions.py 14339000
+#
+#
+# Update the first line of this script to be the same python3 executable as
+# your Home Assistant instance uses.
+# 
+# To use the integration, add the following to your configuration.yaml file
+# (without the comments, obviously!)
+# ------------------------
+# command_line:
+#   - sensor:
+#       name: "River conditions"
+#       unique_id: river_conditions
+#       command: '/home/homeassistant/bin/riverconditions.py 14339000'
+#       scan_interval: 1800
+#       json_attributes:
+#         - data
+#       value_template: 'Rogue River conditions at Dodge Bridge'
+# ------------------------
+# You can use any value you want for value_template.
+# Scan interval should be relatively long, since the values aren't updated
+# frequently. Minimum interval should be 600 seconds (every 10 minutes).
+#
+# Next, add one or more sensors corresponding to the conditions you want to
+# track in your system. For example,
+# ------------------------
+# template:
+#   - sensors:
+#     river_height:
+#       friendly_name: "River height"
+#       device_class: distance
+#       value_template: "{{ state_attr('sensor.river_conditions', 'data')['height'] | round(1) }}"
+#     river_flow:
+#       friendly_name: "River flow"
+#       device_class: volume_flow_rate
+#       unit_of_measurement: "cfs"
+#       value_template: "{{ state_attr('sensor.river_conditions', 'data')['flow'] | round(0) }}"
+# ------------------------
+# Note that height and flow are both contained within the 'data' attribute of the river_conditions
+# sensor populated by the command.
+#
+#
 #
 #==========================================================================
 # Copyright 2025 Ethan L. Miller (code@ethanmiller.us)