Move scripts in nxt.command module, and add manual pages

nxt_filer is still in scripts directory, it might be split out of
NXT-Python project.

Author: schodet

.builds/debian-testing.yml

@@ -2,6 +2,7 @@ image: debian/testing
 packages:
   - python3-usb
   - python3-bluetooth
+  - python3-pil
   - python3-sphinx
   - python3-sphinx-rtd-theme
   - python3-pytest

.builds/debian.yml

@@ -5,6 +5,7 @@ environment:
 packages:
   - python3-usb
   - python3-bluetooth
+  - python3-pil
   - python3-sphinx
   - python3-sphinx-rtd-theme
   - python3-pytest

.builds/freebsd.yml

@@ -6,6 +6,7 @@ packages:
   - python311
   - py311-pytest
   - py311-pyusb
+  - py311-pillow
   - py311-pip
   - py311-tox
 sources:

docs/commands/common_options.rst

@@ -0,0 +1,34 @@
+Common options
+--------------
+
+Those options are common to programs using NXT-Python.
+
+--backend NAME
+   Enable given backend. Can be used several times to enable several backends.
+   One of :mod:`~nxt.backend.usb`, :mod:`~nxt.backend.bluetooth`,
+   :mod:`~nxt.backend.socket` or :mod:`~nxt.backend.devfile`.
+
+--config NAME
+   Name of configuration file section to use.
+
+--config-filename PATH
+   Path to configuration file. Can be used several times to use several
+   configuration files.
+
+--name NAME
+   Name of NXT brick (for example: NXT). Useful to find the right brick if
+   several bricks are connected.
+
+--host ADDRESS
+   Bluetooth address of the NXT brick (for example: 00:16:53:01:02:03).
+
+--server-host HOST
+   Server address or name to connect to when using :mod:`~nxt.backend.socket`
+   backend.
+
+--server-port PORT
+   Server port to connect to when using :mod:`~nxt.backend.socket` backend.
+
+--filename FILENAME
+   Device filename (for example: :file:`/dev/rfcomm0`), when using
+   `~nxt.backend.devfile` backend.

docs/commands/common_see_also.rst

@@ -0,0 +1,6 @@
+.. only:: man
+
+   See also
+   --------
+
+   NXT-Python documentation <https://ni.srht.site/nxt-python/latest/>

docs/commands/index.rst

@@ -0,0 +1,10 @@
+Commands
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   nxt-push
+   nxt-screenshot
+   nxt-server
+   nxt-test

docs/commands/nxt-push.rst

@@ -0,0 +1,50 @@
+Manual page for nxt-push
+========================
+
+Synopsis
+--------
+
+**nxt-push**
+[**--backend** *NAME*]
+[**--config** *NAME*]
+[**--config-filename** *PATH*]
+[**--name** *NAME*]
+[**--host** *ADDRESS*]
+[**--server-host** *HOST*]
+[**--server-port** *PORT*]
+[**--filename** *FILENAME*]
+[**--log-level** *LEVEL*]
+*FILE*...
+
+Description
+-----------
+
+:program:`nxt-push` uploads files to a connected NXT brick file system.
+
+The NXT brick can be connected using USB, Bluetooth or over the network.
+
+
+Options
+-------
+
+*FILE*...
+   Names of files to send to the NXT brick.
+
+--log-level LEVEL
+   Set the log level. One of **DEBUG**, **INFO**, **WARNING**, **ERROR**, or
+   **CRITICAL**. Messages whose level is below the current log level will not
+   be displayed.
+
+
+.. include:: common_options.rst
+
+
+Example
+-------
+
+``nxt-push --host 00:16:53:01:02:03 MotorControl22.rxe``
+   Sends the ``MotorControl22.rxe`` file to a connected NXT using its
+   Bluetooth address to find it.
+
+
+.. include:: common_see_also.rst

docs/commands/nxt-screenshot.rst

@@ -0,0 +1,54 @@
+Manual page for nxt-screenshot
+==============================
+
+Synopsis
+--------
+
+**nxt-screenshot**
+[**--backend** *NAME*]
+[**--config** *NAME*]
+[**--config-filename** *PATH*]
+[**--name** *NAME*]
+[**--host** *ADDRESS*]
+[**--server-host** *HOST*]
+[**--server-port** *PORT*]
+[**--filename** *FILENAME*]
+[**--log-level** *LEVEL*]
+*FILE*
+
+Description
+-----------
+
+:command:`nxt-screenshot` takes a capture of a connected NXT brick and write
+the captured image to a *FILE*.
+
+The NXT brick can be connected using USB, Bluetooth or over the network.
+
+A wide range of image formats is supported, thanks to the Python Imaging
+Library.
+
+
+Options
+-------
+
+*FILE*
+   Filename to write captured image to.
+
+--log-level LEVEL
+   Set the log level. One of **DEBUG**, **INFO**, **WARNING**, **ERROR**, or
+   **CRITICAL**. Messages whose level is below the current log level will not
+   be displayed.
+
+
+.. include:: common_options.rst
+
+
+Example
+-------
+
+``nxt-screenshot --host 00:16:53:01:02:03 capture.png``
+   Capture screen from connected NXT using its Bluetooth address. Save the
+   result image in ``capture.png``.
+
+
+.. include:: common_see_also.rst

docs/commands/nxt-server.rst

@@ -0,0 +1,55 @@
+Manual page for nxt-server
+==========================
+
+Synopsis
+--------
+
+**nxt-server**
+[**--backend** *NAME*]
+[**--config** *NAME*]
+[**--config-filename** *PATH*]
+[**--name** *NAME*]
+[**--host** *ADDRESS*]
+[**--server-host** *HOST*]
+[**--server-port** *PORT*]
+[**--filename** *FILENAME*]
+[**-p|--port** *PORT*]
+[**--log-level** *LEVEL*]
+
+Description
+-----------
+
+:command:`nxt-server` serves an interface to a connected NXT brick over the
+network.
+
+The NXT brick can be connected using USB, Bluetooth or over the network.
+
+
+Options
+-------
+
+-p|--port *PORT*
+   Set the bind port. Same value must be given to the client using
+   **--server-port** or inside Python code. Default port is 2727.
+
+--log-level LEVEL
+   Set the log level. One of **DEBUG**, **INFO**, **WARNING**, **ERROR**, or
+   **CRITICAL**. Messages whose level is below the current log level will not
+   be displayed.
+
+
+.. include:: common_options.rst
+
+Example
+-------
+
+``nxt-server --host 00:16:53:01:02:03``
+   Starting the server on a computer connected to a NXT brick, accepting
+   connection on default port 2727.
+
+``nxt-test --server-host 192.168.1.2``
+   Assuming the first computer has address 192.168.1.2, remotely connect to
+   the server to run a test.
+
+
+.. include:: common_see_also.rst

docs/commands/nxt-test.rst

@@ -0,0 +1,72 @@
+Manual page for nxt-test
+========================
+
+Synopsis
+--------
+
+**nxt-test**
+[**--backend** *NAME*]
+[**--config** *NAME*]
+[**--config-filename** *PATH*]
+[**--name** *NAME*]
+[**--host** *ADDRESS*]
+[**--server-host** *HOST*]
+[**--server-port** *PORT*]
+[**--filename** *FILENAME*]
+[**--no-sound**]
+[**--log-level** *LEVEL*]
+
+Description
+-----------
+
+:command:`nxt-test` tests connection with a NXT brick. It allows to debug the
+NXT-Python setup.
+
+The NXT brick can be connected using USB, Bluetooth or over the network.
+
+
+Options
+-------
+
+--no-sound
+   Be quiet, disable the sound test.
+
+--log-level LEVEL
+   Set the log level. One of **DEBUG**, **INFO**, **WARNING**, **ERROR**, or
+   **CRITICAL**. Messages whose level is below the current log level will not
+   be displayed.
+
+
+.. include:: common_options.rst
+
+Examples
+--------
+
+Running for a NXT brick connected using USB::
+
+   $ nxt-test
+   Finding brick...
+   NXT brick name: NXT
+   Host address: 00:16:53:01:02:03
+   Bluetooth signal strengths: (0, 0, 0, 0)
+   Free user flash: 48480
+   Protocol version 1.124
+   Firmware version 1.29
+   Battery level 8433 mV
+   Play test sound...done
+
+To report problems, please enable debug logs::
+
+   $ nxt-test --log-level DEBUG
+
+When debugging Bluetooth connection problems, try to give the address
+explicitly::
+
+   $ nxt-test --log-level DEBUG --host 00:16:53:01:02:03
+
+The address can be found in the "Settings" menu, under "NXT Version" screen,
+it is the last line labeled "ID". Add the colon to separate each pair of
+digits.
+
+
+.. include:: common_see_also.rst