Add python telemetry docs (#2583)

source/docs/software/telemetry/datalog-download.rst

@@ -83,6 +83,6 @@ The Driver Station software can download WPILogs. Click on the gear icon and sel
 Custom Processing of Data Logs
 ------------------------------
 
-For more advanced processing of data logs (e.g. for processing of binary values that can't be converted to CSV), WPILib provides a ``DataLogReader`` class for reading data logs in `Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/datalog/DataLogReader.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1log_1_1_data_log_reader.html>`__, or `Python <https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/examples/printlog/datalog.py>`__.  For other languages, the `data log format <https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/datalog.adoc>`__ is also documented.
+For more advanced processing of data logs (e.g. for processing of binary values that can't be converted to CSV), WPILib provides a ``DataLogReader`` class for reading data logs in `Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/datalog/DataLogReader.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1log_1_1_data_log_reader.html>`__, or :external:py:class:`Python <wpiutil.log.DataLogReader>`. There is also a pure python datalog reader (`datalog.py <https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/examples/printlog/datalog.py>`__). For other languages, the `data log format <https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/doc/datalog.adoc>`__ is also documented.
 
 DataLogReader provides a low-level view of a data log, in that it supports iterating over a data log's control and data records and decoding of common data types, but does not provide any higher level abstractions such as a NetworkTables-like map of entries.  The printlog example in `Java <https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/src/printlog/java/printlog/PrintLog.java>`__ and `C++ <https://github.com/wpilibsuite/allwpilib/blob/main/wpiutil/examples/printlog/printlog.cpp>`__ (and the Python ``datalog.py``) demonstrates basic usage.

source/docs/software/telemetry/datalog.rst

@@ -15,7 +15,7 @@ Data logs consist of a series of timestamped records.  Control records allow sta
 Standard Data Logging using DataLogManager
 ------------------------------------------
 
-The ``DataLogManager`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DataLogManager.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_data_log_manager.html>`__) provides a centralized data log that provides automatic data log file management.  It automatically cleans up old files when disk space is low and renames the file based either on current date/time or (if available) competition match number.  The data file will be saved to a USB flash drive in a folder called ``logs`` if one is attached, or to ``/home/lvuser/logs`` otherwise.
+The ``DataLogManager`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj/DataLogManager.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc_1_1_data_log_manager.html>`__, :external:py:class:`Python <wpilib.DataLogManager>`) provides a centralized data log that provides automatic data log file management.  It automatically cleans up old files when disk space is low and renames the file based either on current date/time or (if available) competition match number.  The data file will be saved to a USB flash drive in a folder called ``logs`` if one is attached, or to ``/home/lvuser/logs`` otherwise.
 
 .. note:: USB flash drives need to be formatted as FAT32 to work with the roboRIO.  NTFS or exFAT formatted drives will not work.
 
@@ -41,6 +41,12 @@ The most basic usage of DataLogManager only requires a single line of code (typi
         // Starts recording to data log
         frc::DataLogManager::Start();
 
+    .. code-block:: python
+
+        from wpilib import DataLogManager
+
+        DataLogManager.start()
+
 DataLogManager provides a convenience function (``DataLogManager.log()``) for logging of text messages to the ``messages`` entry in the data log. The message is also printed to standard output, so this can be a replacement for ``System.out.println()``.
 
 DataLogManager also records the current roboRIO system time (in UTC) to the data log every ~5 seconds to the ``systemTime`` entry in the data log.  This can be used to (roughly) synchronize the data log with other records such as DS logs or match video.
@@ -82,10 +88,23 @@ DataLogManager by default does not record joystick data.  The ``DriverStation``
         // (alternatively) Record only DS control data
         DriverStation::StartDataLog(DataLogManager::GetLog(), false);
 
+    .. code-block:: python
+
+        from wpilib import DataLogManager, DriverStation
+
+        # Starts recording to data log
+        DataLogManager.start()
+
+        # Record both DS control and joystick data
+        DriverStation.startDataLog(DataLogManager.getLog())
+
+        # (alternatively) Record only DS control data
+        DriverStation.startDataLog(DataLogManager.getLog(), False)
+
 Custom Data Logging using DataLog
 ---------------------------------
 
-The ``DataLog`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/datalog/DataLog.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1log_1_1_data_log.html>`__) and its associated LogEntry classes (e.g. ``BooleanLogEntry``, ``DoubleLogEntry``, etc) provides low-level access for writing data logs.
+The ``DataLog`` class (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/datalog/DataLog.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1log_1_1_data_log.html>`__, :external:py:class:`Python <wpiutil.log.DataLog>`) and its associated LogEntry classes (e.g. ``BooleanLogEntry``, ``DoubleLogEntry``, etc) provides low-level access for writing data logs.
 
 .. note:: Unlike NetworkTables, there is no change checking performed.  **Every** call to a ``LogEntry.append()`` function will result in a record being written to the data log.  Checking for changes and only appending to the log when necessary is the responsibility of the caller.
 
@@ -153,3 +172,31 @@ The LogEntry classes can be used in conjunction with DataLogManager to record va
             myStringLog.Append("wow!");
           }
         }
+
+    .. code-block:: python
+
+        from wpilib import DataLogManager, TimedRobot
+        from wpiutil.log import (
+            DataLog,
+            BooleanLogEntry,
+            DoubleLogEntry,
+            StringLogEntry,
+        )
+
+        class MyRobot(TimedRobot):
+            def robotInit(self):
+                # Starts recording to data log
+                DataLogManager.start()
+
+                # Set up custom log entries
+                log = DataLogManager.getLog()
+                self.myBooleanLog = BooleanLogEntry(log, "/my/boolean")
+                self.myDoubleLog = DoubleLogEntry(log, "/my/double")
+                self.myStringLog = StringLogEntry(log, "/my/string")
+
+            def teleopPeriodic(self):
+                if ...:
+                    # Only log when necessary
+                    self.myBooleanLog.append(True)
+                    self.myDoubleLog.append(3.5)
+                    self.myStringLog.append("wow!")

source/docs/software/telemetry/robot-telemetry-with-sendable.rst

@@ -10,7 +10,7 @@ WPILib provides this functionality with the ``Sendable`` interface.  Classes tha
 What is Sendable?
 -----------------
 
-``Sendable`` (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/sendable/Sendable.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_sendable.html>`__) is an interface provided by WPILib to facilitate robot telemetry.  Classes that implement ``Sendable`` can declaratively send their state to the dashboard - once declared, WPILib will automatically send the telemetry values every robot loop.  This removes the need for teams to handle the iteration-to-iteration logic of sending and receiving values from the dashboard, and also allows teams to separate their telemetry code from their robot logic.
+``Sendable`` (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/sendable/Sendable.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_sendable.html>`__, :external:py:class:`Python <wpiutil.Sendable>`) is an interface provided by WPILib to facilitate robot telemetry.  Classes that implement ``Sendable`` can declaratively send their state to the dashboard - once declared, WPILib will automatically send the telemetry values every robot loop.  This removes the need for teams to handle the iteration-to-iteration logic of sending and receiving values from the dashboard, and also allows teams to separate their telemetry code from their robot logic.
 
 Many WPILib classes (such as :ref:`Commands <docs/software/dashboards/shuffleboard/advanced-usage/shuffleboard-commands-subsystems:Commands and Subsystems>`) already implement ``Sendable``, and so can be sent to the dashboard without any user modification.  Users are also able to easily extend their own classes to implement ``Sendable``.
 
@@ -33,4 +33,10 @@ To send a ``Sendable`` object to the dashboard, simply use the dashboard's ``put
 
         frc::SmartDashboard::PutData("Arm PID", &armPIDController);
 
+    .. code-block:: python
+
+        from wpilib import SmartDashboard
+
+        SmartDashboard.putData("Arm PID", armPIDController)
+
 Additionally, some ``Sendable`` classes bind setters to the data values sent *from the dashboard to the robot*, allowing remote tuning of robot parameters.

source/docs/software/telemetry/writing-sendable-classes.rst

@@ -24,7 +24,7 @@ To enable the automatic updating of values by WPILib "in the background", ``Send
 The SendableBuilder Class
 -------------------------
 
-As seen above, the ``initSendable`` method takes a single parameter, ``builder``, of type ``SendableBuilder`` (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/sendable/SendableBuilder.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_sendable_builder.html>`__).  This builder exposes methods that allow binding of getters and setters to dashboard names, as well as methods for safely ensuring that values consumed *from* the dashboard do not cause unsafe robot behavior.
+As seen above, the ``initSendable`` method takes a single parameter, ``builder``, of type ``SendableBuilder`` (`Java <https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/util/sendable/SendableBuilder.html>`__, `C++ <https://github.wpilib.org/allwpilib/docs/release/cpp/classwpi_1_1_sendable_builder.html>`__, :external:py:class:`Python <wpiutil.SendableBuilder>`).  This builder exposes methods that allow binding of getters and setters to dashboard names, as well as methods for safely ensuring that values consumed *from* the dashboard do not cause unsafe robot behavior.
 
 Databinding with addProperty Methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^