Merge pull request #1446 from Bastian-Krause/bst/steplogger-improvements

StepLogger documentation and warning fix

Author: Bastian-Krause

doc/configuration.rst

@@ -3434,6 +3434,9 @@ Reporters
 
 StepReporter
 ~~~~~~~~~~~~
+.. warning::
+    The StepReporter is deprecated, use the `StepLogger`_ instead.
+
 The :any:`StepReporter` outputs individual labgrid steps to `STDOUT`.
 
 .. doctest::
@@ -3471,6 +3474,32 @@ The Reporter can be stopped with a call to the stop function:
 Stopping the ConsoleLoggingReporter if it has not been started will raise an
 AssertionError, as will starting an already started StepReporter.
 
+Loggers
+-------
+
+StepLogger
+~~~~~~~~~~
+The :any:`StepLogger` logs individual labgrid steps.
+
+Logging can be set up via ``labgrid.logging.basicConfig()``.
+
+.. doctest::
+
+    >>> import logging
+    >>> from labgrid.logging import basicConfig, StepLogger
+    >>> basicConfig(level=logging.INFO)
+    >>> StepLogger.start()
+
+The logger can be stopped with a call to the stop function:
+
+.. doctest::
+
+    >>> from labgrid.logging import StepLogger
+    >>> StepLogger.stop()
+
+Stopping the StepLogger if it has not been started will raise an
+AssertionError, as will starting an already started StepLogger.
+
 Environment Configuration
 -------------------------
 The environment configuration for a test environment consists of a YAML file

doc/development.rst

@@ -764,7 +764,7 @@ Step Tracing
 
 The Step infrastructure already collects timing and nesting information on
 executed commands, but is currently only used in the pytest plugin or via the
-standalone StepReporter.
+standalone StepLogger (or deprecated StepReporter).
 By writing these events to a file (or sqlite database) as a trace, we can
 collect data over multiple runs for later analysis.
 This would become more useful by passing recognized events (stack traces,

labgrid/logging.py

@@ -136,7 +136,7 @@ def __attrs_post_init__(self):
         from warnings import warn
 
         warn(
-            "StepLogger should not be instantiated, use StepReporter.start()/.stop() instead.",
+            "StepLogger should not be instantiated, use StepLogger.start()/.stop() instead.",
             DeprecationWarning,
             stacklevel=2,
         )