doc: man: Add some details to subcommands

The subcommands descriptions for create, release-from and flashscript
had some extra details in the old rst manpages, not available in the
argparse/cli help. Migrate these descriptions into argparse.

Signed-off-by: Jonas Rebmann <jre@pengutronix.de>

Author: jonrebm

labgrid/remote/client.py

@@ -1810,7 +1810,10 @@ def man_add_parser(self, name, **kwargs):
     subparser = subparsers.add_parser("show", help="show a place and related resources")
     subparser.set_defaults(func=ClientSession.print_place)
 
-    subparser = subparsers.add_parser("create", help="add a new place")
+    subparser = subparsers.add_parser(
+        "create",
+        help="add a new place with the name specified via ``--place`` or the ``LG_PLACE`` environment variable",
+    )
     subparser.set_defaults(func=ClientSession.add_place)
 
     subparser = subparsers.add_parser("delete", help="delete an existing place")
@@ -1858,7 +1861,10 @@ def man_add_parser(self, name, **kwargs):
     subparser.set_defaults(func=ClientSession.release)
 
     subparser = subparsers.add_parser(
-        "release-from", help="atomically release a place, but only if locked by a specific user"
+        "release-from",
+        help="atomically release a place, but only if locked by a specific user",
+        epilog="Note that this command returns success as long as the specified user no longer owns the place, "
+        "meaning it may be acquired by another user or not at all.",
     )
     subparser.add_argument("acquired", metavar="HOST/USER", help="User and host to match against when releasing")
     subparser.set_defaults(func=ClientSession.release_from)
@@ -1908,7 +1914,7 @@ def man_add_parser(self, name, **kwargs):
     subparser.add_argument("--name", "-n", help="optional resource name")
     subparser.set_defaults(func=ClientSession.fastboot)
 
-    subparser = subparsers.add_parser("flashscript", help="run flash script")
+    subparser = subparsers.add_parser("flashscript", help="Run arbitrary script with arguments to flash device")
     subparser.add_argument("script", help="Flashing script")
     subparser.add_argument("script_args", metavar="ARG", nargs=argparse.REMAINDER, help="script arguments")
     subparser.add_argument("--name", "-n", help="optional resource name")

man/labgrid-client.1

@@ -257,7 +257,7 @@ Log output to FILE
 .UNINDENT
 .SS labgrid\-client create
 .sp
-add a new place
+add a new place with the name specified via \fB\-\-place\fP or the \fBLG_PLACE\fP environment variable
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -401,7 +401,7 @@ optional resource name
 .UNINDENT
 .SS labgrid\-client flashscript
 .sp
-run flash script
+Run arbitrary script with arguments to flash device
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -548,6 +548,8 @@ usage: labgrid\-client release\-from HOST/USER
 .B host/user
 User and host to match against when releasing
 .UNINDENT
+.sp
+Note that this command returns success as long as the specified user no longer owns the place, meaning it may be acquired by another user or not at all.
 .SS labgrid\-client release|unlock
 .sp
 release a place