[docs] improved root command help

Author: MrClock8163

docs/about.rst

@@ -40,8 +40,10 @@ These have to be set before specifying the command groups.
 
     iman --info --file iman.log measure ...
 
-Usage
------
+.. tip::
 
-.. click:: instrumentman:cli
-    :prog: iman
+    See the command help for all logging options.
+
+    .. code-block:: shell
+
+        iman -h

src/instrumentman/__init__.py

@@ -53,8 +53,43 @@ def cli(
     dateformat: str = "%Y-%m-%d %H:%M:%S",
     rotate: tuple[int, int] | None = None
 ) -> None:
-    """Automated measurement programs and related utilities for surveying
-    instruments."""
+    """
+    \b
+    +--------------------------------------------------------------------+
+    |                                                                    |
+    |       .---------.                                                  |
+    |      / +-------+ \\                                                 |
+    |     .__| +---+ |__.                                                |
+    |     |  | |   | |  |    ___                                         |
+    |     |  |=| @ |=|  |   |_ _|          _ __ ___     __ _   _ __      |
+    |     |  | |   | |  |    | |   _____  | '_ ` _ \\   / _` | | '_ \\     |
+    |     |  | +---+ |  |    | |  |_____| | | | | | | | (_| | | | | |    |
+    |    .+--+-------+--+.  |___|         |_| |_| |_|  \\__,_| |_| |_|    |
+    |    | .----.   123  |                                               |
+    |    | |____|   456  |                                               |
+    |    '_______________'                                               |
+    |                                                                    |
+    +--------------------------------------------------------------------+
+
+    Instrumentman (or I-man for short) is a collection of command line programs
+    related to the automation of surveying instruments (primarily robotic total
+    stations) through serial line command protocols (mainly Leica GeoCom).
+
+    The individual commands are available through their respective action
+    based command groups. The help page for each command can be accessed
+    through the -h/--help option. Logging can be set up with options of this
+    root command.
+
+    Examples:
+
+    iman download file -h
+
+    iman --debug --file log.log measure inclination -o incline.csv -p 3 COM1
+
+    iman calc sets merged.json results.csv
+
+    iman terminal
+    """
     configure_logging(
         protocol,
         debug,

src/instrumentman/utils.py

@@ -63,7 +63,7 @@ def com_port_argument() -> Callable[[F], F]:
     return argument(
         "port",
         help=(
-            "serial port that the instrument is connected to (must be a valid "
+            "Serial port that the instrument is connected to (must be a valid "
             "identifier like COM1 or /dev/usbtty0)"
         ),
         type=str
@@ -76,7 +76,7 @@ def com_timeout_option(
     return option(
         "-t",
         "--timeout",
-        help="serial timeout",
+        help="Serial timeout",
         type=IntRange(min=0),
         default=default
     )
@@ -88,7 +88,7 @@ def com_baud_option(
     return option(
         "-b",
         "--baud",
-        help="serial speed",
+        help="Serial speed",
         type=Choice(
             [
                 "1200",
@@ -112,19 +112,18 @@ def com_baud_option(
 def com_option_group() -> Callable[[F], F]:
     return option_group(
         "Connection options",
-        "Options related to the serial connection",
         com_baud_option(),
         com_timeout_option(),
         option(
             "-r",
             "--retry",
-            help="number of connection retry attempts",
+            help="Number of connection retry attempts",
             type=IntRange(min=0, max=10),
             default=1
         ),
         option(
             "--sync-after-timeout",
-            help="attempt to synchronize message que after a timeout",
+            help="Attempt to synchronize message que after a timeout",
             is_flag=True
         )
     )
@@ -133,74 +132,73 @@ def com_option_group() -> Callable[[F], F]:
 def logging_option_group() -> Callable[[F], F]:
     return option_group(
         "Logging options",
-        "Options related to the logging functionalities.",
         option(
             "--protocol",
             help=(
-                "log debug level messages and above, "
+                "Log debug level messages and above, "
                 "including protocol messages"
             ),
             is_flag=True
         ),
         option(
             "--debug",
-            help="log debug level messages and above",
+            help="Log debug level messages and above",
             is_flag=True
         ),
         option(
             "--info",
-            help="log information level messages and above",
+            help="Log information level messages and above",
             is_flag=True
         ),
         option(
             "--warning",
-            help="log warning level messages and above",
+            help="Log warning level messages and above",
             is_flag=True
         ),
         option(
             "--error",
-            help="log error level messages and above",
+            help="Log error level messages and above",
             is_flag=True
         ),
         option(
             "--critical",
-            help="log critical error level messages",
+            help="Log critical error level messages",
             is_flag=True
         ),
         option(
             "--file",
-            help="log to file",
+            help="Log to file",
             type=file_path(readable=False)
         ),
         option(
             "--stdout",
-            help="log to standard output",
+            help="Log to standard output",
             is_flag=True
         ),
         option(
             "--stderr",
-            help="log to standard error",
+            help="Log to standard error",
             is_flag=True
         ),
         option(
             "--format",
             help=(
-                "logging format string (as accepted by the `logging` package "
+                "Logging format string (as accepted by the `logging` package "
                 "in '{' style)"
             ),
             type=str,
             default="{asctime} <{name}> [{levelname}] {message}"
         ),
         option(
             "--dateformat",
-            help="date-time format spec (as accepted by `strftime`)",
+            help="Date-time format spec (as accepted by `strftime`)",
             type=str,
             default="%Y-%m-%d %H:%M:%S"
         ),
         option(
             "--rotate",
             help=(
-                "number of backup log files to rotate, and maximum size "
+                "Number of backup log files to rotate, and maximum size "
                 "(in bytes) of a log file before rotation"
             ),
             type=(IntRange(1), IntRange(1))