docs/shell.rst: Auto-generate shell command reference

We use a slightly modified version of sphinx-argparse
(with patch https://github.com/alex-rudakov/sphinx-argparse/pull/136 applied)
in order to generate the command reference for each shell command in the
manual.

As the upstream repository seems unmaintained for ~2 years, let's use
the osmocom 'fork' with that above-mentioned patch applied.

Change-Id: I134f267cf53c7ecbc8cbfb33a8766d63bf4a8582

contrib/jenkins.sh

@@ -21,6 +21,7 @@ python -m unittest discover -v -s tests/
 # attempt to build documentation
 pip install sphinx
 pip install sphinxcontrib-napoleon
+pip3 install -e 'git+https://github.com/osmocom/sphinx-argparse@master#egg=sphinx-argparse'
 (cd docs && make html)
 
 # run the test with physical cards

docs/conf.py

@@ -29,6 +29,7 @@ author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
 # ones.
 extensions = [
         "sphinx.ext.autodoc",
+        "sphinxarg.ext",
         "sphinx.ext.autosectionlabel",
         "sphinx.ext.napoleon"
 ]

docs/shell.rst

@@ -85,32 +85,41 @@ This will
 
 change_chv
 ~~~~~~~~~~
-
+.. argparse::
-This command allows you to change a CHV (PIN).
+   :module: pySim-shell
+   :func: Iso7816Commands.change_chv_parser
 
 
 disable_chv
 ~~~~~~~~~~~
+.. argparse::
+   :module: pySim-shell
+   :func: Iso7816Commands.disable_chv_parser
 
-This command allows you to disable a CHV (PIN).
 
 enable_chv
 ~~~~~~~~~~
-
+.. argparse::
-This command allows you to enable a CHV (PIN).
+   :module: pySim-shell
+   :func: Iso7816Commands.enable_chv_parser
 
 
 unblock_chv
 ~~~~~~~~~~~
+.. argparse::
+   :module: pySim-shell
+   :func: Iso7816Commands.unblock_chv_parser
 
-This command allows you to unblock a CHV (PIN) using the PUK.
 
 verify_chv
 ~~~~~~~~~~
-
 This command allows you to verify a CHV (PIN), which is how the specifications call
 it if you authenticate yourself with the said CHV/PIN.
 
+.. argparse::
+   :module: pySim-shell
+   :func: Iso7816Commands.verify_chv_parser
+
 
 
 pySim commands
@@ -128,30 +137,26 @@ Display human readable file description for the currently selected file.
 
 dir
 ~~~
-
+.. argparse::
-::
+   :module: pySim-shell
-
+   :func: PySimCommands.dir_parser
-  usage: dir [-h] [--fids] [--names] [--apps] [--all]
-
-  Show a listing of files available in currently selected DF or MF
-
-  optional arguments:
-    -h, --help  show this help message and exit
-    --fids      Show file identifiers
-    --names     Show file names
-    --apps      Show applications
-    --all       Show all selectable identifiers and names
 
 
 export
 ~~~~~~
+.. argparse::
+   :module: pySim-shell
+   :func: PySimCommands.export_parser
+
 
 tree
 ~~~~
+FIXME
+
 
 verify_adm
 ~~~~~~~~~~
-
+FIXME
 
 
 Linear Fixed EF commands
@@ -161,15 +166,30 @@ These commands become enabled only when your currently selected file is of *Line
 
 read_record
 ~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: LinFixedEF.ShellCommands.read_rec_parser
+
 
 read_record_decoded
 ~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: LinFixedEF.ShellCommands.read_rec_dec_parser
+
 
 update_record
 ~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: LinFixedEF.ShellCommands.upd_rec_parser
+
 
 update_record_decoded
 ~~~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: LinFixedEF.ShellCommands.upd_rec_dec_parser
 
 
 
@@ -181,15 +201,30 @@ These commands become enabled only when your currently selected file is of *Tran
 
 read_binary
 ~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: TransparentEF.ShellCommands.read_bin_parser
+
 
 read_binary_decoded
 ~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: TransparentEF.ShellCommands.read_bin_dec_parser
+
 
 update_binary
 ~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: TransparentEF.ShellCommands.upd_bin_parser
+
 
 update_binary_decoded
 ~~~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.filesystem
+   :func: TransparentEF.ShellCommands.upd_bin_dec_parser