doc: Improve documentation in various places

* don't duplicate information between .rst files and docstrings
* if there's more than a trivial single-line documentation, put it as
  docstring into the python source and use ".. argparse" to pul it into
  the manual
* add documentation for some commands for which it was missing
* show one level deeper in the navigation table, listing the commands

Change-Id: Ib88bb7d12faaac7d149ee1f6379bc128b83bbdd5

6 files changed, 91 insertions, 28 deletions

diff --git a/docs/conf.py b/docs/conf.py
index a96b87e..6fea583 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@ sys.path.insert(0, os.path.abspath('..'))
 # -- Project information -----------------------------------------------------
 
 project = 'osmopysim-usermanual'
-copyright = '2009-2021 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
+copyright = '2009-2022 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
 author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle'
 
 
diff --git a/docs/index.rst b/docs/index.rst
index c647880..471802a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,7 +34,7 @@ pySim consists of several parts:
 * the [legacy] :ref:`pySim-prog and pySim-read tools<Legacy tools>`
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents:
 
    shell
diff --git a/docs/shell.rst b/docs/shell.rst
index 0f3139f..f24dc93 100644
--- a/docs/shell.rst
+++ b/docs/shell.rst
@@ -164,9 +164,6 @@ unblock_chv
 
 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
@@ -178,9 +175,6 @@ Deactivate the currently selected file.  This used to be called INVALIDATE in TS
 
 activate_file
 ~~~~~~~~~~~~~
-Activate the specified file.  This used to be called REHABILITATE in TS 11.11.
-You need to specify the name or FID of the file to activate.
-
 .. argparse::
    :module: pySim-shell
    :func: Iso7816Commands.activate_file_parser
@@ -212,6 +206,7 @@ including the electrical power down.
    :func: Iso7816Commands.suspend_uicc_parser
 
 
+
 pySim commands
 --------------
 
@@ -221,7 +216,6 @@ a complex sequence of card-commands.
 
 desc
 ~~~~
-
 Display human readable file description for the currently selected file.
 
 
@@ -231,6 +225,17 @@ dir
    :module: pySim-shell
    :func: PySimCommands.dir_parser
 
+Example:
+::
+
+  pySIM-shell (MF)> dir
+  MF
+  3f00
+   ..          ADF.USIM    DF.SYSTEM   EF.DIR      EF.UMPC
+   ADF.ARA-M   DF.EIRENE   DF.TELECOM  EF.ICCID    MF
+   ADF.ISIM    DF.GSM      EF.ARR      EF.PL
+  14 files
+
 
 export
 ~~~~~~
@@ -250,15 +255,27 @@ all/most files.
 
 tree
 ~~~~
-
 Display a tree of the card filesystem.  It is important to note that this displays a tree
 of files that might potentially exist (based on the card profile).  In order to determine if
 a given file really exists on a given card, you have to try to select that file.
 
+Example:
+::
+
+  pySIM-shell (MF)> tree --help
+  EF.DIR                    2f00 Application Directory
+  EF.ICCID                  2fe2 ICC Identification
+  EF.PL                     2f05 Preferred Languages
+  EF.ARR                    2f06 Access Rule Reference
+  EF.UMPC                   2f08 UICC Maximum Power Consumption
+  DF.TELECOM                7f10 None
+    EF.ADN                  6f3a Abbreviated Dialing Numbers
+  ...
+
+
 
 verify_adm
 ~~~~~~~~~~
-
 Verify the ADM (Administrator) PIN specified as argument.  This is typically needed in order
 to get write/update permissions to most of the files on SIM cards.
 
@@ -286,8 +303,6 @@ bulk_script
    :module: pySim-shell
    :func: PysimApp.bulk_script_parser
 
-Run a script for bulk-provisioning of multiple cards.
-
 
 echo
 ~~~~
@@ -296,6 +311,13 @@ echo
    :func: PysimApp.echo_parser
 
 
+apdu
+~~~~
+.. argparse::
+   :module: pySim-shell
+   :func: PySimCommands.apdu_cmd_parser
+
+
 
 Linear Fixed EF commands
 ------------------------
@@ -484,6 +506,26 @@ authenticate
    :module: pySim.ts_31_102
    :func: ADF_USIM.AddlShellCommands.authenticate_parser
 
+terminal_profile
+~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.ts_31_102
+   :func: ADF_USIM.AddlShellCommands.term_prof_parser
+
+envelope
+~~~~~~~~
+.. argparse::
+   :module: pySim.ts_31_102
+   :func: ADF_USIM.AddlShellCommands.envelope_parser
+
+envelope_sms
+~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.ts_31_102
+   :func: ADF_USIM.AddlShellCommands.envelope_sms_parser
+
+
+
 
 ARA-M commands
 --------------
@@ -546,21 +588,14 @@ Perform Config handshake with ARA-M applet: Tell it our version and retrieve its
 
 NOTE: Not supported in all ARA-M implementations.
 
-.. argparse::
-   :module: pySim.ara_m
-   :func: ADF_ARAM.AddlShellCommands.get_config_parser
-
 
 aram_store_ref_ar_do
 ~~~~~~~~~~~~~~~~~~~~
-Store a [new] access rule on the ARA-M applet.
-
 .. argparse::
    :module: pySim.ara_m
    :func: ADF_ARAM.AddlShellCommands.store_ref_ar_do_parse
 
 For example, to store an Android UICC carrier privilege rule for the SHA1 hash of the certificate used to sign the CoIMS android app of Supreeth Herle (https://github.com/herlesupreeth/CoIMS_Wiki) you can use the following command:
-
 ::
 
   pySIM-shell (MF/ADF.ARA-M)> aram_store_ref_ar_do --aid FFFFFFFFFFFF --device-app-id E46872F28B350B7E1F140DE535C2A8D5804F0BE3 --android-permissions 0000000000000001 --apdu-always
diff --git a/pySim-shell.py b/pySim-shell.py
index ec417c7..0753b10 100755
--- a/pySim-shell.py
+++ b/pySim-shell.py
@@ -683,7 +683,8 @@ class PySimCommands(CommandSet):
     def do_apdu(self, opts):
         """Send a raw APDU to the card, and print SW + Response.
         DANGEROUS: pySim-shell will not know any card state changes, and
-        not continue to work as expected if you e.g. select a different file."""
+        not continue to work as expected if you e.g. select a different
+        file."""
         data, sw = self._cmd.card._scc._tp.send_apdu(opts.APDU)
         self._cmd.poutput("SW: %s %s, RESP: %s" % (sw, self._cmd.rs.interpret_sw(sw), data))
 
@@ -739,7 +740,9 @@ class Iso7816Commands(CommandSet):
 
     @cmd2.with_argparser(verify_chv_parser)
     def do_verify_chv(self, opts):
-        """Verify (authenticate) using specified PIN code"""
+        """Verify (authenticate) using specified CHV (PIN) code, which is how the specifications
+        call it if you authenticate yourself using the specified PIN.  There usually is at least PIN1 and
+        PIN2."""
         pin = self.get_code(opts.pin_code)
         (data, sw) = self._cmd.card._scc.verify_chv(opts.pin_nr, h2b(pin))
         self._cmd.poutput("CHV verification successful")
@@ -812,7 +815,8 @@ class Iso7816Commands(CommandSet):
     activate_file_parser.add_argument('NAME', type=str, help='File name or FID of file to activate')
     @cmd2.with_argparser(activate_file_parser)
     def do_activate_file(self, opts):
-        """Activate the specified EF"""
+        """Activate the specified EF. This used to be called REHABILITATE in TS 11.11 for classic
+        SIM.  You need to specify the name or FID of the file to activate."""
         (data, sw) = self._cmd.rs.activate_file(opts.NAME)
 
     def complete_activate_file(self, text, line, begidx, endidx) -> List[str]:
diff --git a/pySim/ara_m.py b/pySim/ara_m.py
index 0928f8d..59f205c 100644
--- a/pySim/ara_m.py
+++ b/pySim/ara_m.py
@@ -311,7 +311,7 @@ class ADF_ARAM(CardADF):
                 self._cmd.poutput_json(res_do.to_dict())
 
         def do_aram_get_config(self, opts):
-            """GET DATA [Config] on the ARA-M Applet"""
+            """Perform GET DATA [Config] on the ARA-M Applet: Tell it our version and retrieve its version."""
             res_do = ADF_ARAM.get_config(self._cmd.card._scc._tp)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
@@ -345,7 +345,7 @@ class ADF_ARAM(CardADF):
 
         @cmd2.with_argparser(store_ref_ar_do_parse)
         def do_aram_store_ref_ar_do(self, opts):
-            """Perform STORE DATA [Command-Store-REF-AR-DO] to store a new access rule."""
+            """Perform STORE DATA [Command-Store-REF-AR-DO] to store a (new) access rule."""
             # REF
             ref_do_content = []
             if opts.aid:
diff --git a/pySim/ts_31_102.py b/pySim/ts_31_102.py
index 3995dfa..c6bfa2d 100644
--- a/pySim/ts_31_102.py
+++ b/pySim/ts_31_102.py
@@ -1310,18 +1310,42 @@ class ADF_USIM(CardADF):
             (data, sw) = self._cmd.card._scc.authenticate(opts.rand, opts.autn)
             self._cmd.poutput_json(data)
 
+        term_prof_parser = argparse.ArgumentParser()
+        term_prof_parser.add_argument('PROFILE', help='Hexstring of encoded terminal profile')
+
+        @cmd2.with_argparser(term_prof_parser)
         def do_terminal_profile(self, arg):
-            """Send a TERMINAL PROFILE command to the card."""
+            """Send a TERMINAL PROFILE command to the card.
+            This is used to inform the card about which optional
+            features the terminal (modem/phone) supports, particularly
+            in the context of SIM Toolkit, Proactive SIM and OTA.  You
+            must specify a hex-string with the encoded terminal profile
+            you want to send to the card."""
             (data, sw) = self._cmd.card._scc.terminal_profile(arg)
             self._cmd.poutput('SW: %s, data: %s' % (sw, data))
 
+        envelope_parser = argparse.ArgumentParser()
+        envelope_parser.add_argument('PAYLOAD', help='Hexstring of encoded payload to ENVELOPE')
+
+        @cmd2.with_argparser(envelope_parser)
         def do_envelope(self, arg):
-            """Send an ENVELOPE command to the card."""
+            """Send an ENVELOPE command to the card.  This is how a
+            variety of information is communicated from the terminal
+            (modem/phone) to the card, particularly in the context of
+            SIM Toolkit, Proactive SIM and OTA."""
             (data, sw) = self._cmd.card._scc.envelope(arg)
             self._cmd.poutput('SW: %s, data: %s' % (sw, data))
 
+        envelope_sms_parser = argparse.ArgumentParser()
+        envelope_sms_parser.add_argument('TPDU', help='Hexstring of encoded SMS TPDU')
+
+        @cmd2.with_argparser(envelope_sms_parser)
         def do_envelope_sms(self, arg):
-            """Send an ENVELOPE command to the card."""
+            """Send an ENVELOPE(SMS-PP-Download) command to the card.
+            This emulates a terminal (modem/phone) having received a SMS
+            with a PID of 'SMS for the SIM card'.  You can use this
+            command in the context of testing OTA related features
+            without a modem/phone or a cellular netwokr."""
             tpdu_ie = SMS_TPDU()
             tpdu_ie.from_bytes(h2b(arg))
             dev_ids = DeviceIdentities(