update documentation

docs/source/gdbcheatsheet.rst

@@ -9,33 +9,87 @@ gdb Cheat Sheet
 Note on Supported Commands
 --------------------------
 
-Any valid ``gdb`` command can be used in ``mdb`` (as long as it runs in remote execution mode -- but
-that's nearly all the useful ones I can think of). The main exceptions are ``start`` and ``run`` and
-these wouldn't work in MPI mode anyway because you cannot (as far as I know) restart and MPI
+Most valid ``gdb`` commands can be used in ``mdb`` (as long as they run in remote execution mode --
+but that's nearly all the useful ones I can think of). The main exceptions are ``start`` and ``run``
+and these wouldn't work in MPI mode anyway because you cannot (as far as I know) restart and MPI
 application from within the process.
 
 ``mdb`` launches the binary to stop at ``main`` by default, which can optionally overridden to any
 other valid breakpoint if this is not suitable (see :ref:`quick_start` for more info). Therefore
 instead of using ``start`` or ``run`` commands, as you can non-MPI applications, ``mdb`` will
 already be waiting at the breakpoint specified by ``-b/--breakpt``.
 
+For MPI debugging ``gdb``'s reverse commands (e.g., ``reverse-next``, ``reverse-step`` etc.) are not
+supported. Each ``gdb`` instance is not MPI-aware and you cannot step backwards through
+``MPI_init()``, for example. If you want to "go backwards" you should restart the ``mdb`` debug
+session.
+
 .. _gdbcheat:
 
 Useful Commands
 ---------------
 
-This section is a WIP and will be updated shortly.
-
 The following commands may be helpful when using ``mdb``. All of these can be passed to ``gdb``
 using the command ``command [gdb command]`` (or optionally specify which ranks to run the command on
 with ``command [ranks] [gdb command]``). A full list of ``gdb`` commands can be found in `gdb's
 manual <https://sourceware.org/gdb/current/onlinedocs/gdb.html>`_.
 
-+-------------+--------------------------+-------------------------+-----------+
-| Command     | Effect                   | Example                 | Aliases   |
-+=============+==========================+=========================+===========+
-| backtrace   | print backtrace          | command 1-4 backtrace   | bt        |
-+-------------+--------------------------+-------------------------+-----------+
-| continue    | continue running program | command continue        | c         |
-+-------------+--------------------------+-------------------------+-----------+
+.. csv-table:: Moving through the program
+   :header: Command , Action                     , Example                    , Aliases
+
+   ``next``         , run to next line           , ``command n``              , ``n``
+   ``step``         , step into function         , ``command s``              , ``s``
+   ``backtrace``    , print backtrace            , ``command bt``             , ``bt`` and ``where``
+   ``continue``     , continue running program   , ``command c``              , ``c``
+   ``until``        , run until ``{expression}`` , ``command u {expression}`` , ``u``
+   ``up``           , move up one frame          , ``command up``             , ``up``
+   ``down``         , move down one frame        , ``command down``           , ``do``
+
+.. csv-table:: Breakpoints and Watchpoints
+   :header: Command    , Action               , Example                                 , Aliases
+
+   ``breakpoint``      , set a breakpoint     , ``command b {expression}``              , ``b``
+                       ,                      , ``command b [filename]:[line_no]``      ,
+                       , (conditional)        , ``command b [func_name] if myrank < 2`` ,
+   ``watchpoint``      , set a watchpoint     , ``command watch [variable_name]``       , ``watch``
+                       , (on write)           , ``command watch foo``                   ,
+                       , (on read)            , ``command rwatch foo``                  ,
+                       , (on read-write)      , ``command awatch foo``                  ,
+   ``delete [num]``    , delete breakpoint #2 , ``command del 2``                       , ``del``
+
+.. csv-table:: Displaying Information
+   :header: Command     , Action                                      , Example                 , Aliases
+
+   ``print``            , print variable ``{var}``                    , ``command p {var}``     , ``p``
+   ``display``          , show variable ``{var}`` after every command , ``command disp {var}``  , ``disp``
+   ``info {option}``    , print information for:                      ,                         ,
+                        , (breakpoints)                               , ``command info break``  , ``info b``
+                        , (locals)                                    , ``command info locals`` , ``info loc``
+
+.. csv-table:: Changing Execution
+   :header: Command , Action                             , Example                           , Aliases
+
+   ``set variable`` , change value of variable ``{var}`` , ``command set var {var}={value}`` , ``set var``
+
+Single Key Mode (TUI)
+---------------------
+
+This can be used inside an interactive ``gdb`` session when the ``tui`` is activated. To enter
+Single Key Mode press ``CTRL-x s``. To exit press ``q``. This allows you to use a single key press
+to issue the following commands:
+
+.. csv-table:: Single Key Mode
+   :header: Key, Command
 
+   ``c``, ``continue``
+   ``d``, ``down``
+   ``f``, ``finish``
+   ``n``, ``next``
+   ``o``, ``nexti`` (the letter "o" stands for "step [o]ver")
+   ``r``, ``run``
+   ``s``, ``step``
+   ``i``, ``stepi`` (the letter "i" stands for "step [i]nto")
+   ``u``, ``up``
+   ``v``, ``info locals``
+   ``w``, ``where``
+   ``q``, (exit Single Key Mode)

docs/source/index.rst

@@ -20,15 +20,14 @@ MPI is implemented in and that I have had a chance to test.
    :caption: Getting Started:
 
    Installation <installation>
-   Quick Start <quickstart>
-   Example Debug Session <example>
+   Quick Start <quick-start>
 
 .. toctree::
    :maxdepth: 2
    :caption: Reference:
    :hidden:
 
-   mdb Command Line Interface (CLI) <click>
+   mdb Command Line Interface (CLI) <mdb-cli>
    gdb Cheat Sheet <gdbcheatsheet>
 
 .. toctree::

docs/source/mdb.rst

@@ -4,9 +4,8 @@
 mdb package
 ===========
 
-Submodules
-----------
-
+.. Submodules
+.. ----------
 
 .. automodule:: mdb.mdb
    :members:
@@ -37,9 +36,9 @@ Submodules
    :members:
    :show-inheritance:
 
-Module contents
----------------
+.. Module contents
+.. ---------------
 
-.. automodule:: mdb
-   :members:
-   :show-inheritance:
+.. .. automodule:: mdb
+..    :members:
+..    :show-inheritance:

mdb/mdb_shell.py

@@ -42,23 +42,30 @@
 def buffered_input_filter(
     handle_input: Callable[[str], str]
 ) -> Callable[[bytes], bytes]:
-    """Wrap functions to generate arguments for `pexpect.interact` filters.
+    """Wrap functions to generate arguments for ``pexpect.interact`` filters.
 
     Wraps a callback function with a buffer so that instead of receiving each
     character as it is typed, the filter function is given the current command
     string. The wrapper also augments/overrides the interaction with common
     substitutions for control characters:
-    - `Ctrl-d` will send `INTERACT_ESCAPE_CHARACTER` to end the interaction
-      instead of `quit` to the gdb shell.
 
-    The `handle_input` argument is only called after each newline or carriage
-    return, and should return characters to be sent to the GDB shell else an
+        - ``Ctrl-d`` will send ``INTERACT_ESCAPE_CHARACTER`` to end the
+          interaction instead of ``quit`` to the gdb shell.
+
+    The ``handle_input`` argument is only called after each newline or carriage
+    return, and should return characters to be sent to the gdb shell else an
     empty string.
 
-    Note that if `handle_input` is to modify the string in any way other than
+    Note that if ``handle_input`` is to modify the string in any way other than
     by sending new characters to the shell, it must also include the backspace
     characters needed to remove (parts of) the current string and include the
-    newline character to execute the command in GDB.
+    newline character to execute the command in gdb.
+
+    Args:
+        handle_input: function that takes a ``str`` and returns a ``str``.
+
+    Returns:
+        function that takes ``bytes`` and returns ``bytes``.
     """
 
     # closure memory

mdb/utils.py

@@ -31,11 +31,11 @@ def strip_control_characters(text: str) -> str:
 
 def parse_ranks(ranks: str) -> set[int]:
     """Parse a string of ranks into a set of integers. E.g.,
-    `parse_ranks('1,3-5')` would return the following: `set(1,3,4,5)`.
+    ``parse_ranks("1,3-5")`` would return the following: ``set(1,3,4,5)``.
 
     Args:
         ranks: string of ranks using either a mix of comma separation and
-        ranges using hyphen `-`.
+          ranges using hyphen.
 
     Returns:
         A set of ranks represented by integers.