Generate labgrid-client subcommand and option documentation from argparse

[jonrebm]

Manage the documentation with sphinx and auto-document labgrid-client arguments and subcommands from source using sphinx-argparse.

Sections from the original man/labgrid-client.rst which are not obsoleted by the autogenerated reference are migrated into sphinx. Sphinx generates both the manpages as well as their html documentation counterpart.

I believe the result of this is much more useful than the current manpages we have that just don't sufficiently document usage of the subcommands.

See the readthedocs builds for results.

[codecov]

Codecov Report

❌ Patch coverage is 94.11765% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 55.6%. Comparing base (e380181) to head (d2f2131).
⚠️ Report is 10 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
labgrid/remote/client.py	94.1%	2 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff           @@
##           master   #1707   +/-   ##
======================================
  Coverage    55.6%   55.6%           
======================================
  Files         172     172           
  Lines       13471   13477    +6     
======================================
+ Hits         7500    7506    +6     
  Misses       5971    5971           

Flag	Coverage Δ
3.10	55.6% <94.1%> (+<0.1%)	⬆️
3.11	55.6% <94.1%> (+<0.1%)	⬆️
3.12	55.6% <94.1%> (+<0.1%)	⬆️
3.13	55.6% <94.1%> (+<0.1%)	⬆️
3.9	55.7% <94.1%> (+<0.1%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Bastian-Krause]

Can we get rid of the "Default: " lines? Most of them are either misleading (expose internal implementation details) or redundant. Ideally the defaults should be part of the help strings where useful.

Here's what I mean:

labgrid-client
Labgrid is a scalable infrastructure and test architecture for embedded (linux) systems.

This is the client to control a boards status and interface with it on remote machines.

usage: labgrid-client [-h] [-x ADDRESS] [-c CONFIG] [-p PLACE] [-s STATE]
[-i INITIAL_STATE] [-d] [-v] [-P PROXY]
COMMAND ...
Named Arguments
-x, --coordinator
coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408)

-c, --config
env config file (default: value from env variable LG_ENV)

-p, --place
place name/alias (default: value from env variable LG_PLACE)

-s, --state
strategy state to switch into before command (default: value from env varibale LG_STATE)

-i, --initial-state
strategy state to force into before switching to desired state

-d, --debug
enable debug mode (show python tracebacks)

Default: False

Here.

-v, --verbose
Default: 0

Here.

-P, --proxy
proxy connections via given ssh host

Sub-commands
monitor
monitor events from the coordinator

labgrid-client monitor [-h]
resources (r)
list available resources

labgrid-client resources [-h] [-a] [-e EXPORTER]
[--sort-by-matched-place-change]
[match]
Positional Arguments
match
Named Arguments
-a, --acquired
Default: False

Here.

-e, --exporter
--sort-by-matched-place-change
sort by matched place’s changed date (oldest first) and show place and date

Default: False

Here.

places (p)
list available places

labgrid-client places [-h] [-a] [-r] [--sort-last-changed]
Named Arguments
-a, --acquired
Default: False

Here.

-r, --released
Default: False

Here.

--sort-last-changed
sort by last changed date (oldest first)

Default: False

Here.

who
list acquired places by user

labgrid-client who [-h] [-e]
Named Arguments
-e, --show-exporters
show exporters currently used by each place

Default: False

Here.

show
show a place and related resources

[...]

labgrid-client acquire [-h] [--allow-unmatched]
Named Arguments
--allow-unmatched
allow missing resources for matches when locking the place

Default: False

Here.

release (unlock)
release a place

labgrid-client release [-h] [-k]
Named Arguments
-k, --kick
release a place even if it is acquired by a different user

Default: False

Here.

[...]

labgrid-client console [-h] [-l] [-o] [--logfile FILE] [name]
Positional Arguments
name
optional resource name

Named Arguments
-l, --loop
keep trying to connect if the console is unavailable

Default: False

Here.

-o, --listenonly
do not modify local terminal, do not send input from stdin

Default: False

Here.

[...]

labgrid-client forward [-h] [--name NAME] [--local [LOCAL:]REMOTE]
[--remote REMOTE:LOCAL]
Named Arguments
--name, -n
optional resource name

--local, -L
Forward local port LOCAL to remote port REMOTE. If LOCAL is unspecified, an arbitrary port will be chosen

Default: []

Here.

--remote, -R
Forward remote port REMOTE to local port LOCAL

Default: []

Here.

[...]

write-files
copy files onto mass storage device

labgrid-client write-files [OPTION]... -T SOURCE DEST
labgrid-client write-files [OPTION]... [-t DIRECTORY] SOURCE...
Positional Arguments
SOURCE
source file(s) to copy

DEST
destination file name for SOURCE

Named Arguments
-w, --wait
storage poll timeout in seconds

Default: 10.0

-p, --partition
partition number to mount or 0 to mount whole disk (default: 1)

Default: 1

Redundant.

-t, --target-directory
copy all SOURCE files into DIRECTORY (default: partition root)

Default: /

Redundant.

-T
copy SOURCE file and rename to DEST

Default: False

Here.

--name, -n
optional resource name

write-image
write an image onto mass storage

labgrid-client write-image [-h] [-w WAIT] [-p PARTITION] [--skip SKIP]
[--seek SEEK] [--mode {dd,bmaptool}] [--name NAME]
filename
Positional Arguments
filename
filename to boot on the target

Named Arguments
-w, --wait
Default: 10.0

-p, --partition
partition number to write to

--skip
skip n 512-sized blocks at start of input

Default: 0

Here.

--seek
skip n 512-sized blocks at start of output

Default: 0

Here.

--mode
Possible choices: dd, bmaptool

Choose tool for writing images (default: dd)

Default: dd

Redundant.

--name, -n
optional resource name

reserve
create a reservation

labgrid-client reserve [-h] [--wait] [--shell] [--prio PRIO]
KEY=VALUE [KEY=VALUE ...]
Positional Arguments
KEY=VALUE
required tags

Named Arguments
--wait
wait until the reservation is allocated

Default: False

Here.

--shell
format output as shell variables

Default: False

Here.

--prio
priority relative to other reservations (default 0)

Default: 0.0

Redundant.

[...]

labgrid-client export [-h] [--format {shell,shell-export,json}] filename
Positional Arguments
filename
output filename

Named Arguments
--format
Possible choices: shell, shell-export, json

output format (default: shell-export)

Default: shell-export

Redundant.

version
show version

labgrid-client version [-h]

[Bastian-Krause]

One more observation: In "Named Arguments" there is no distinction between flags (e.g. -v, --verbose) and options expecting a value (e.g. -x, --coordinator). The usage contains these information. Is there an easy way of adding that?

[jonrebm]

@Bastian-Krause sadly, no. Generally I prefer the manpage format of autoprogram over that of sphinx-argparse, as it is more compact, idiomatic and does show option parameters:

LABGRID-CLIENT
usage: labgrid-client [-h] [-x ADDRESS] [-c CONFIG] [-p PLACE] [-s STATE] [-i INITIAL_STATE] [-d] [-v] [-P PROXY] COMMAND ...

-h, --help
        show this help message and exit

-x <address>, --coordinator <address>
        coordinator HOST[:PORT] (default: value from env variable LG_COORDINATOR, otherwise 127.0.0.1:20408)

We opted for sphinx-argparse for now in order to be able to replace subcommand descriptions. Maybe we keep an eye on progress of both alternatives.

That said, shpinx-argparse is fairly simple and it would be easy for us to add missing functionality at a later time if necessary.