Generate labgrid-client subcommand and option documentation from argparse

doc/conf.py

@@ -40,9 +40,14 @@
               'sphinx.ext.napoleon',
               'sphinx.ext.coverage',
               'sphinx.ext.viewcode',
+              'sphinxarg.ext', # sphinx-argparse
               'sphinx.ext.autosectionlabel',
               'sphinx_rtd_theme']
 
+# Required. Otherwise pages using sphinx-argparse will produce many warnings
+# (duplicate labels due to duplicate headings such as "named arguments")
+autosectionlabel_maxdepth = 3
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']
 
@@ -156,7 +161,19 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     (master_doc, 'labgrid', 'labgrid Documentation',
-     [author], 1)
+     [author], 1),
+    ('man/client', 'labgrid-client', 'labgrid\'s client interface to control boards',
+     [author], 1),
+    ('man/coordinator', 'labgrid-coordinator', 'managing labgrid resources and places',
+     [author], 1),
+    ('man/device-config', 'labgrid-device-config', 'test configuration files',
+     [author], 5),
+    ('man/exporter', 'labgrid-exporter', 'interface to control boards',
+     [author], 1),
+    ('man/pytest', 'labgrid-pytest', 'labgrid integration for pytest',
+     [author], 7),
+    ('man/suggest', 'labgrid-suggest', 'generator for YAML config files',
+     [author], 1),
 ]
 
 
@@ -181,7 +198,11 @@
 autodoc_mock_imports = ['onewire',
                         'gi',
                         'gi.repository',
-                        'vxi11']
+                        'vxi11',
+                        'pysnmp',
+                        'kasa',
+                        'kasa.iot',
+                        ]
 
 # -- Options for autosection ----------------------------------------------
 autosectionlabel_prefix_document = True

doc/man.rst

@@ -2,7 +2,11 @@ Manual Pages
 ============
 
 .. toctree::
+   :maxdepth: 2
+
    man/client
+   man/coordinator
    man/device-config
    man/exporter
-   man/coordinator
+   man/pytest
+   man/suggest

doc/man/client.rst

@@ -1,2 +1,162 @@
 .. _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.
+
+.. currentmodule:: labgrid.remote.client
+
+
+.. argparse::
+   :module: labgrid.remote.client
+   :func: get_parser
+   :prog: labgrid-client
+   :nodefault:
+
+
+   help : @skip
+        skip.
+
+   complete : @skip
+        skip.
+
+   available subcommands : @skip
+        skip.
+
+   create : @replace
+        add a new place with the name specified via ``--place`` or the
+        ``LG_PLACE`` environment variable.
+
+   release-from : @replace
+        Atomically release a place, but only if acquired by a specific user.
+
+        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.
+
+   flashscript : @replace
+        Run arbitrary script with arguments to flash device
+
+
+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)

doc/man/coordinator.rst

@@ -1,2 +1,34 @@
-.. _labgrid-coordinator:
-.. include:: ../../man/labgrid-coordinator.rst
+=====================
+ labgrid-coordinator
+=====================
+
+labgrid-coordinator managing labgrid resources and places
+=========================================================
+
+SYNOPSIS
+--------
+
+``labgrid-coordinator`` ``--help``
+
+DESCRIPTION
+-----------
+Labgrid is a scalable infrastructure and test architecture for embedded (linux)
+systems.
+
+This is the man page for the coordinator. Clients and exporters connect to the
+coordinator to publish resources, manage place configuration and handle mutual
+exclusion.
+
+OPTIONS
+-------
+-h, --help
+    display command line help
+-l ADDRESS, --listen ADDRESS
+    make coordinator listen on host and port
+-d, --debug
+    enable debug mode
+
+SEE ALSO
+--------
+
+``labgrid-client``\(1), ``labgrid-exporter``\(1)