fix(logging): Unify output messages, notes, and warning formatting

Author: radimkarnis

README.md

@@ -1,6 +1,6 @@
 # esptool.py
 
-A Python-based, open-source, platform-independent utility to communicate with the ROM bootloader in Espressif chips.
+A Python-based, open-source, platform-independent serial utility for flashing, provisioning, and interacting with Espressif SoCs.
 
 [![Test esptool](https://github.com/espressif/esptool/actions/workflows/test_esptool.yml/badge.svg?branch=master)](https://github.com/espressif/esptool/actions/workflows/test_esptool.yml) [![Build esptool](https://github.com/espressif/esptool/actions/workflows/build_esptool.yml/badge.svg?branch=master)](https://github.com/espressif/esptool/actions/workflows/build_esptool.yml)
 

docs/en/esptool/flashing-firmware.rst

@@ -79,33 +79,36 @@ Change ``PORT`` to the name of :ref:`actually used serial port <serial-port>` an
 
     $ python -m esptool -p /dev/tty.usbserial-0001 -b 460800 --before default_reset --after hard_reset --chip {IDF_TARGET_PATH_NAME} write-flash --flash-mode dio --flash-size detect --flash-freq 40m {IDF_TARGET_BOOTLOADER_OFFSET} build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin 0x10000 build/hello_world.bin
     esptool.py v4.8.1
-    Serial port /dev/tty.usbserial-0001
+    Serial port /dev/tty.usbserial-0001:
     Connecting.........
-    Chip is ESP32-D0WD (revision 1)
-    Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
-    Crystal is 40MHz
-    MAC: de:ad:be:ef:1d:ea
-    Uploading stub...
-    Running stub...
-    Stub running...
-    Changing baud rate to 460800
+    Connected to ESP32 on /dev/tty.usbserial-0001:
+    Chip type:          ESP32-D0WD (revision 1)
+    Features:           WiFi, BT, Dual Core, 240MHz, Vref calibration in eFuse, Coding Scheme None
+    Crystal frequency:  40MHz
+    MAC:                de:ad:be:ef:1d:ea
+
+    Uploading stub flasher...
+    Running stub flasher...
+    Stub flasher running.
+    Changing baud rate to 460800...
     Changed.
     Configuring flash size...
-    Auto-detected Flash size: 16MB
+    Auto-detected flash size: 4MB
     Flash will be erased from 0x00001000 to 0x00007fff...
     Flash will be erased from 0x00008000 to 0x00008fff...
     Flash will be erased from 0x00010000 to 0x00039fff...
-    Flash params set to 0x0240
-    SHA digest in image updated
+    Flash parameters set to 0x0240.
+    SHA digest in image updated.
     Compressed 25536 bytes to 15935...
-    Wrote 25536 bytes (15935 compressed) at 0x00001000 in 0.7 seconds (effective 275.5 kbit/s)...
+    Wrote 25536 bytes (15935 compressed) at 0x00001000 in 0.7 seconds (effective 275.5 kbit/s).
     Hash of data verified.
     Compressed 3072 bytes to 103...
-    Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 334.1 kbit/s)...
+    Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.1 seconds (effective 334.1 kbit/s).
     Hash of data verified.
     Compressed 169232 bytes to 89490...
-    Wrote 169232 bytes (89490 compressed) at 0x00010000 in 2.6 seconds (effective 513.0 kbit/s)...
+    Wrote 169232 bytes (89490 compressed) at 0x00010000 in 2.6 seconds (effective 513.0 kbit/s).
     Hash of data verified.
+
     Hard resetting via RTS pin...
 
 It is now possible to unplug the flashed device and repeat the process by connecting another one and running the command again.

docs/en/index.rst

@@ -1,7 +1,8 @@
 Esptool.py Documentation
 ========================
 
-This is the documentation for ``esptool.py`` - a Python-based, open source, platform independent serial communication tool. Esptool communicates with the ROM bootloader (or flasher stub) in `Espressif SoCs <https://www.espressif.com/en/products/hardware/socs>`_.
+This is the documentation for ``esptool.py`` - a Python-based, open-source, platform-independent utility for flashing, provisioning, and interacting with Espressif SoCs. Esptool communicates with the ROM bootloader (or the flasher stub) in `Espressif SoCs <https://www.espressif.com/en/products/hardware/socs>`_.
+
 The flasher stub is a small program included with esptool that replaces the original ROM bootloader in the chip to fix some of its limitations and bugs. See :ref:`stub` for more details.
 
 ``esptool.py``, ``espefuse.py`` and ``espsecure.py`` are a complete toolset for working with Espressif chips. They can do a number of things, for example:

docs/en/migration-guide.rst

@@ -202,3 +202,12 @@ This change affects most of the commands and the following options: ``--flash_si
 **Migration Steps:**
 
 1. Replace all underscores in command and option names with ``-`` in your scripts and CI pipelines.
+
+Log Format Changes
+******************
+
+A significant amount of changes have been made to the log styling and formatting in ``v5``. Some of the messages, warnings, and errors are now formatted differently or reworded to provide more context and improve readability. Exhaustive list of changed messages won't be provided.
+
+**Migration Steps:**
+
+1. Make sure to adjust any of your scripts, asserts, CI workflows, or others to accommodate the new/changed format of messages. If you are parsing the log output (not recommended), consider importing esptool as a module and using the public API (see :ref:`here <scripting>`) to get the information you need.