doc: man: Generate labgrid-client manpages from argparse via sphinx

The old process was to manually duplicate information between the
argparse struct in labgrid/remote/client.py and man/labgrid-client.rst
which would then be translated to a manpage in man/labgrid-client.1 and
also tracked in version control.

The man/labgrid-client.rst file was also sourced in doc/man/client.rst
for sphinx to build html documentation of the labgrid-client cli
documentation.

Due to this duplication, labgrid-client command documentation was
incomplete and inconsistend with argparse documentation accessible via
the -h switch.

Use sphinx-argparse to generate usage info from the argparse struct
returned by get_parser() in labgrid/remote/client.py as part of
doc/man/client.rst. Move documentation missing from the argparse struct
from man/labgrid-client.1 to doc/man/client.rst. Generate both html cli
documentation as well as the manpage from that using make -C doc html.

Signed-off-by: Jonas Rebmann <[email protected]>

Author: jonrebm

doc/conf.py

@@ -40,9 +40,12 @@
               'sphinx.ext.napoleon',
               'sphinx.ext.coverage',
               'sphinx.ext.viewcode',
+              'sphinxarg.ext', # sphinx-argparse
               'sphinx.ext.autosectionlabel',
               'sphinx_rtd_theme']
 
+suppress_warnings = ['autosectionlabel.*']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']
 
@@ -156,6 +159,8 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     (master_doc, 'labgrid', 'labgrid Documentation',
+     [author], 1),
+    ('man/client', 'labgrid-client', 'labgrid\'s client interface to control boards',
      [author], 1)
 ]
 
@@ -181,7 +186,14 @@
 autodoc_mock_imports = ['onewire',
                         'gi',
                         'gi.repository',
-                        'vxi11']
+                        'vxi11',
+                        'pysnmp',
+                        'kasa',
+                        'labgrid.driver.power.eaton',
+                        'labgrid.driver.power.poe_mib',
+                        'labgrid.driver.power.raritan',
+                        'labgrid.driver.power.tplink',
+                        ]
 
 # -- Options for autosection ----------------------------------------------
 autosectionlabel_prefix_document = True

doc/man/client.rst

@@ -1,2 +1,138 @@
 .. _labgrid-client:
-.. include:: ../../man/labgrid-client.rst
+
+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.
+
+.. argparse::
+   :module: labgrid.remote.client
+   :func: get_parser
+   :prog: labgrid-client
+   :noepilog:
+   :nodescription:
+
+   help : @skip
+        skip help
+
+Configuration File
+------------------
+The configuration file follows the description in ``labgrid-device-config``\(5).
+
+Environment Variables
+---------------------
+Various labgrid-client commands use the following environment variable:
+
+LG_PLACE
+~~~~~~~~
+This variable can be used to specify a place without using the ``-p`` option, the ``-p`` option overrides it.
+
+LG_TOKEN
+~~~~~~~~
+This variable can be used to specify a reservation for the ``wait`` command and
+for the ``+`` place expansion.
+
+LG_STATE
+~~~~~~~~
+This variable can be used to specify a state which the device transitions into
+before executing a command. Requires a configuration file and a Strategy
+specified for the device.
+
+LG_INITIAL_STATE
+~~~~~~~~~~~~~~~~
+This variable can be used to specify an initial state the device is known to
+be in.
+This is useful during development. The Strategy used must implement the
+``force()`` method.
+A desired state must be set using ``LG_STATE`` or ``-s``/``--state``.
+
+LG_ENV
+~~~~~~
+This variable can be used to specify the configuration file to use without
+using the ``--config`` option, the ``--config`` option overrides it.
+
+LG_COORDINATOR
+~~~~~~~~~~~~~~
+This variable can be used to set the default coordinator in the format
+``HOST[:PORT]`` (instead of using the ``-x`` option).
+
+LG_PROXY
+~~~~~~~~
+This variable can be used to specify a SSH proxy hostname which should be used
+to connect to the coordinator and any resources which are normally accessed
+directly.
+
+LG_HOSTNAME
+~~~~~~~~~~~
+Override the hostname used when accessing a resource. Typically only useful for
+CI pipelines where the hostname may not be consistent between pipeline stages.
+
+LG_USERNAME
+~~~~~~~~~~~
+Override the username used when accessing a resource. Typically only useful for
+CI pipelines where the username may not be consistent between pipeline stages.
+
+LG_SSH_CONNECT_TIMEOUT
+~~~~~~~~~~~~~~~~~~~~~~
+Set the connection timeout when using SSH (The ``ConnectTimeout`` option). If
+unspecified, defaults to 30 seconds.
+
+LG_AGENT_PREFIX
+~~~~~~~~~~~~~~~~~~~~~~
+Add a prefix to ``.labgrid_agent_{agent_hash}.py`` allowing specification for
+where on the exporter it should be uploaded to. 
+
+Matches
+-------
+Match patterns are used to assign a resource to a specific place. The format is:
+exporter/group/cls/name, exporter is the name of the exporting machine, group is
+a name defined within the exporter, cls is the class of the exported resource
+and name is its name. Wild cards in match patterns are explicitly allowed, *
+matches anything.
+
+Adding Named Resources
+----------------------
+If a target contains multiple Resources of the same type, named matches need to
+be used to address the individual resources. In addition to the `match` taken by
+`add-match`, `add-named-match` also takes a name for the resource. The other
+client commands support the name as an optional parameter and will inform the
+user that a name is required if multiple resources are found, but no name is
+given.
+
+If one of the resources should be used by default when no resource name is
+explicitly specified, it can be named ``default``.
+
+Examples
+--------
+
+To retrieve a list of places run:
+
+.. code-block:: bash
+
+   $ labgrid-client places
+
+To access a place, it needs to be acquired first, this can be done by running
+the ``acquire command`` and passing the placename as a -p parameter:
+
+.. code-block:: bash
+
+   $ labgrid-client -p <placename> acquire
+
+Open a console to the acquired place:
+
+.. code-block:: bash
+
+   $ labgrid-client -p <placename> console
+
+Add all resources with the group "example-group" to the place example-place:
+
+.. code-block:: bash
+
+   $ labgrid-client -p example-place add-match */example-group/*/*
+
+See Also
+--------
+
+``labgrid-exporter``\(1)

pyproject.toml

@@ -56,6 +56,7 @@ dynamic = ["version"]  # via setuptools_scm
 doc = [
     "sphinx_rtd_theme>=1.0.0",
     "Sphinx>=2.0.0",
+    "sphinx-argparse",
 ]
 docker = ["docker>=5.0.2"]
 graph = ["graphviz>=0.17.0"]