Fill out sphinx doc. Revise docstrings

docs/commands.rst

@@ -3,26 +3,11 @@ Command Reference
 
 Following *gdb*, we classify commands into the following categories:
 
-* breakpoints -- Making program stop at certain points
-* data -- Examining data
-* files -- Specifying and examining files
-* running -- Running the program
-* stack -- Examining the stack
-* status -- Status inquiries
-* support -- Support facilities
-
-
 .. toctree::
    :maxdepth: 2
 
-   breakpoints
-   data
-   files
-   support
-   running
-
-Stack
-======
-
-Status
-=======
+   commands/breakpoints
+   commands/data
+   commands/files
+   commands/running
+   commands/support

docs/commands/breakpoints.rst

@@ -0,0 +1,13 @@
+Breakpoints
+===========
+
+Making the program stop at certain points
+
+.. toctree::
+   :maxdepth: 1
+
+   breakpoints/break
+   breakpoints/condition
+   breakpoints/disable
+   breakpoints/enable
+   breakpoints/tbreak

docs/commands/breakpoints/break.rst

@@ -0,0 +1,36 @@
+.. _break:
+
+Break
+-----
+
+**break** [*location*] [if *condition*]]
+
+With a line number argument, set a break there in the current file.
+With a function name, set a break at first executable line of that
+function.  Without argument, set a breakpoint at current location.  If
+a second argument is `if`, subsequent arguments given an expression
+which must evaluate to true before the breakpoint is honored.
+
+The location line number may be prefixed with a filename or module
+name and a colon. Files is searched for using *sys.path*, and the `.py`
+suffix may be omitted in the file name.
+
+Examples:
++++++++++
+
+::
+
+   break              # Break where we are current stopped at
+   break if i < j     # Break at current line if i < j
+   break 10           # Break on line 10 of the file we are
+                      # currently stopped at
+   break os.path.join # Break in function os.path.join
+   break os.path:45   # Break on line 45 of os.path
+   break myfile:5 if i < j # Same as above but only if i < j
+   break myfile.py:45 # Break on line 45 of myfile.py
+   break myfile:45    # Same as above.
+
+See also:
++++++++++
+
+:ref:`tbreak <tbreak>`.

docs/commands/breakpoints/condition.rst

@@ -0,0 +1,24 @@
+.. _condition:
+
+Condition
+---------
+
+**condition** *bp_number* *condition*
+
+*bp_number* is a breakpoint number. *condition* is an expression which
+must evaluate to *True* before the breakpoint is honored.  If *condition*
+is absent, any existing condition is removed; i.e., the breakpoint is
+made unconditional.
+
+Examples:
++++++++++
+
+::
+
+   condition 5 x > 10  # Breakpoint 5 now has condition x > 10
+   condition 5         # Remove above condition
+
+See also:
++++++++++
+
+:ref:`break <break>`, :ref:`tbreak <tbreak>`.

docs/commands/breakpoints/delete.rst

@@ -0,0 +1,11 @@
+.. _delete:
+
+Delete
+------
+**delete** [*bpnumber* [*bpnumber*...]]
+
+Delete some breakpoints.
+
+Arguments are breakpoint numbers with spaces in between.  To delete
+all breakpoints, give no argument.  those breakpoints.  Without
+argument, clear all breaks (but first ask confirmation).

docs/commands/breakpoints/disable.rst

@@ -0,0 +1,12 @@
+.. _disable:
+
+Disable
+-------
+**disable** *bpnumber* [*bpnumber* ...]
+
+Disables the breakpoints given as a space separated list of breakpoint
+numbers. See also `info break` to get a list.
+
+See also:
++++++++++
+:ref:`enable <enable>`

docs/commands/breakpoints/enable.rst

@@ -0,0 +1,14 @@
+.. _enable:
+
+Enable
+-------
+**enable** *bpnumber* [*bpnumber* ...]
+
+Enables the breakpoints given as a space separated list of breakpoint
+numbers. See also `info break` to get a list.
+
+See also:
++++++++++
+:ref:`disable <disable>`
+
+.. _tbreak:

docs/commands/breakpoints/tbreak.rst

@@ -0,0 +1,30 @@
+Tbreak
+-------
+**tbreak** [*location*] [**if** *condition*]
+
+With a line number argument, set a break there in the current file.
+With a function name, set a break at first executable line of that
+function.  Without argument, set a breakpoint at current location.  If
+a second argument is `if`, subequent arguments given an expression
+which must evaluate to true before the breakpoint is honored.
+
+The location line number may be prefixed with a filename or module
+name and a colon. Files is searched for using *sys.path*, and the `.py`
+suffix may be omitted in the file name.
+
+Examples:
++++++++++
+
+::
+
+   tbreak     # Break where we are current stopped at
+   tbreak 10  # Break on line 10 of the file we are currently stopped at
+   tbreak os.path.join # Break in function os.path.join
+   tbreak os.path:45   # Break on line 45 of os.path
+   tbreak myfile.py:45 # Break on line 45 of myfile.py
+   tbreak myfile:45    # Same as above.
+
+See also:
++++++++++
+
+:ref:`break <break>`.

docs/commands/data.rst

@@ -0,0 +1,19 @@
+Data
+====
+
+Examining data.
+
+.. toctree::
+   :maxdepth: 1
+
+   data/disassemble
+   data/display
+   data/eval
+   data/examine
+   data/pdef
+   data/pp
+   data/pr
+   data/pydocx
+   data/set
+   data/undisplay
+   data/whatis

docs/commands/data/disassemble.rst

@@ -0,0 +1,35 @@
+.. _disassemble:
+
+Disassemble
+-----------
+
+*disassemble* [*thing*] [*start-line* [*end-line*]]
+
+With no argument, disassemble the current frame. With an integer
+start-line, the disassembly is narrowed to show lines starting at that
+line number or later; with an end-line number, disassembly stops when
+the next line would be greater than that or the end of the code is hit.
+
+If *start-line* or *end-line is* ``.``, ``+``, or ``-``, the current
+line number is used. If instead it starts with a plus or minus prefix to
+a number, then the line number is relative to the current frame number.
+
+With a class, method, function, pyc-file, code or string argument
+disassemble that.
+
+Examples:
++++++++++
+
+::
+
+       disassemble    # Possibly lots of stuff dissassembled
+       disassemble .  # Disassemble lines starting at current stopping point.
+       disassemble +                  # Same as above
+       disassemble +0                 # Same as above
+       disassemble os.path            # Disassemble all of os.path
+       disassemble os.path.normcase   # Disaassemble just method os.path.normcase
+       disassemble -3  # Disassemble subtracting 3 from the current line number
+       disassemble +3  # Disassemble adding 3 from the current line number
+       disassemble 3                  # Disassemble starting from line 3
+       disassemble 3 10               # Disassemble lines 3 to 10
+       disassemble myprog.pyc         # Disassemble file myprog.pyc

docs/commands/data/display.rst

@@ -0,0 +1,19 @@
+.. _display:
+
+Display
+-------
+**display** [*format*] *expression*
+
+Print value of expression *expression* each time the program stops.
+*format* may be used before *expression* and may be one of `/c` for
+char, `/x` for hex, `/o` for octal, `/f` for float or `/s` for string.
+
+For now, display expressions are only evaluated when in the same
+code as the frame that was in effect when the display expression
+was set.  This is a departure from gdb and we may allow for more
+flexibility in the future to specify whether this should be the
+case or not.
+
+With no argument, evaluate and display all currently requested
+auto-display expressions.  Use `undisplay` to cancel display
+requests previously made.