man: Migrate to doc/

As sphinx supports generating manpages, use it to simplify the process
and drop the dependency on rst2man.

All manpages are now tracked in doc/man.

The Makefile in man/ remains for forward compatibility.

Keep tracking manpages themselves in troff format so sphinx is not
required for packaging, slightly update Documentation to reflect the
changes requirements for manpage generation.

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

Author: jonrebm

.github/pull_request_template.md

@@ -33,7 +33,7 @@ Did you test the change locally? If yes, best to mention how you did it in the d
 --->
 - [ ] PR has been tested
 <!---
-If your PR touched the man pages they have to be regenerated by calling make in the man subdirectory of the project
+If your PR touched the man pages in doc/man, or an argparse struct from which manpages are generated, they have to be regenerated by calling make in the man subdirectory of the project. sphinx with our themes and extensions is required for this, see the README for more information,
 --->
 - [ ] Man pages have been regenerated
 

README.rst

@@ -135,6 +135,11 @@ Tests can now run via:
 
    venv $ python -m pytest --lg-env <config>
 
+To install sphinx and the dependencies needed for generating man pages and documentation run:
+
+.. code-block:: bash
+
+   venv $ pip install '.[doc]'
 
 .. |license| image:: https://img.shields.io/badge/license-LGPLv2.1-blue.svg
     :alt: LGPLv2.1

doc/conf.py

@@ -156,7 +156,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),
 ]
 
 
@@ -185,7 +197,10 @@
 autodoc_mock_imports = ['onewire',
                         'gi',
                         'gi.repository',
-                        'vxi11']
+                        'vxi11',
+                        'pysnmp',
+                        'kasa',
+                        'kasa.iot']
 
 # -- Options for autosection ----------------------------------------------
 autosectionlabel_prefix_document = True

doc/man.rst

@@ -3,6 +3,8 @@ Manual Pages
 
 .. toctree::
    man/client
+   man/coordinator
    man/device-config
    man/exporter
-   man/coordinator
+   man/pytest
+   man/suggest

doc/man/client.rst

@@ -1,2 +1,263 @@
 .. _labgrid-client:
-.. include:: ../../man/labgrid-client.rst
+
+================
+ labgrid-client
+================
+
+labgrid-client interface to control boards
+==========================================
+
+SYNOPSIS
+--------
+
+``labgrid-client`` ``--help``
+
+``labgrid-client`` -p <place> <command>
+
+``labgrid-client`` ``places|resources``
+
+DESCRIPTION
+-----------
+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.
+
+OPTIONS
+-------
+-h, --help
+    display command line help
+-p PLACE, --place PLACE
+    specify the place to operate on
+-x ADDRESS, --coordinator ADDRESS
+    coordinator ``HOST[:PORT]`` to connect to, defaults to ``127.0.0.1:20408``
+-c CONFIG, --config CONFIG
+    set the configuration file
+-s STATE, --state STATE
+    set an initial state before executing a command, requires a configuration
+    file and strategy
+-i INITIAL_STATE, --initial-state INITIAL_STATE
+    strategy state to force into before switching to desired state, requires a
+    desired state (``-s``/``--state``/``LG_STATE``)
+-d, --debug
+    enable debugging
+-v, --verbose
+    increase verbosity
+-P PROXY, --proxy PROXY
+    proxy connections over ssh
+
+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.
+
+LABGRID-CLIENT COMMANDS
+-----------------------
+``monitor``                                 Monitor events from the coordinator
+
+``resources (r)``                           List available resources
+
+``places (p)``                              List available places
+
+``who``                                     List acquired places by user
+
+``show``                                    Show a place and related resources
+
+``create``                                  Add a new place (name supplied by -p parameter)
+
+``delete``                                  Delete an existing place
+
+``add-alias`` ``[alias]``                   Add an alias to a place
+
+``del-alias`` ``[alias]``                   Delete an alias from a place
+ 
+``set-comment`` ``[comment]``               Update or set the place comment
+
+``set-tags`` ``[key=value]``                Set place tags (key=value)
+
+``add-match`` ``[match]``                   Add one (or multiple) match pattern(s) to a place, see MATCHES
+
+``del-match`` ``[match]``                   Delete one (or multiple) match pattern(s) from a place, see MATCHES
+
+``add-named-match`` ``[match]`` ``[name]``  Add one match pattern with a name to a place
+
+``acquire (lock)``                          Acquire a place
+
+``allow`` ``[user]``                        Allow another user to access a place
+
+``release (unlock)``                        Release a place
+
+``release-from`` ``[host/user]``            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.
+
+``env``                                     Generate a labgrid environment file for a place
+
+``power (pw)`` ``[action]``                 Change (or get) a place's power status, where action is one of get, on, off, cycle
+
+``io`` ``[action]`` ``[name]``              Interact with GPIO (OneWire, relays, ...) devices, where action is one of high, low, get
+
+``console (con)`` ``[name]``                Connect to the console
+
+``dfu`` ``[arg]``                           Run dfu commands
+
+``fastboot`` ``[arg]``                      Run fastboot with argument
+
+``flashscript`` ``[script]`` ``[arg]``      Run arbitrary script with arguments to flash device
+
+``bootstrap`` ``[filename]``                Start a bootloader
+
+``sd-mux`` ``[action]``                     Switch USB SD Muxer, where action is one of dut (device-under-test), host, off
+
+``usb-mux`` ``[action]``                    Switch USB Muxer, where action is one of off, dut-device, host-dut, host-device, host-dut+host-device
+
+``ssh`` ``[command]``                       Connect via SSH. Additional arguments are passed to ssh.
+
+``scp`` ``[source]`` ``[destination]``      Transfer file via scp (use ':dir/file' for the remote side)
+
+``rsync`` ``[source]`` ``[destination]``    Transfer files via rsync (use ':dir/file' for the remote side)
+
+``sshfs`` ``[remotepath]`` ``[mountpoint]`` Mount a remote path via sshfs
+
+``forward``                                 Forward local port to remote target
+
+``telnet``                                  Connect via telnet
+
+``video``                                   Start a video stream
+
+``audio``                                   Start an audio stream
+
+``tmc`` ``[command]``                       Control a USB TMC device
+
+``write-files`` ``[filename(s)]``           Copy files onto mass storage device
+
+``write-image`` ``[filename]``              Write images onto block devices (USBSDMux, USB Sticks, …)
+
+``reserve`` ``[filter]``                    Create a reservation
+
+``cancel-reservation`` ``[token]``          Cancel a pending reservation
+
+``wait`` ``[token]``                        Wait for a reservation to be allocated
+
+``reservations``                            List current reservations
+
+``export`` ``[filename]``                   Export driver information to file (needs environment with drivers)
+
+``version``                                 Print the labgrid version
+
+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)