Move term_size heuristic to RemoteDebugger constructor, document bett…

…er (gh-485)

doc/starting.rst

@@ -1,5 +1,5 @@
-Getting Started
----------------
+Starting the debugger
+---------------------
 
 To start debugging, simply insert::
 
@@ -81,6 +81,8 @@ connection::
     pudb:6899: Please telnet into 127.0.0.1 6899.
     pudb:6899: Waiting for client...
 
+.. automodule:: pudb.remote
+
 "Reverse" remote debugging
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -106,7 +108,6 @@ Then watch the debugger connect to netcat::
 
     pudb:9999: Now in session with 127.0.0.1:6899.
 
-
 Using the debugger after forking
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

pudb/remote.py

@@ -1,3 +1,10 @@
+"""
+.. autoclass:: RemoteDebugger
+
+.. autofunction:: set_trace
+.. autofunction:: debugger
+"""
+
 __copyright__ = """
 Copyright (C) 2009-2017 Andreas Kloeckner
 Copyright (C) 2014-2017 Aaron Meurer
@@ -77,6 +84,10 @@
 
 
 class RemoteDebugger(Debugger):
+    """
+    .. automethod:: __init__
+    """
+
     me = "pudb"
     _prev_outs = None
     _sock = None
@@ -90,8 +101,24 @@ def __init__(
         term_size=None,
         reverse=False,
     ):
+        """
+        :arg term_size: A two-tuple ``(columns, rows)``, or *None*. If *None*,
+            try to determine the terminal size automatically.
+
+            Currently, this uses a heuristic: It uses the terminal size of the
+            debuggee as that for the debugger. The idea is that you might be
+            running both in two tabs of the same terminal window, hence using
+            terminals of the same size.
+        """
         self.out = out
 
+        if term_size is None:
+            try:
+                s = struct.unpack("hh", fcntl.ioctl(1, termios.TIOCGWINSZ, "1234"))
+                term_size = (s[1], s[0])
+            except Exception:
+                term_size = (80, 24)
+
         self._prev_handles = sys.stdin, sys.stdout
         self._client, (address, port) = self.get_client(
             host=host, port=port, search_limit=port_search_limit, reverse=reverse
@@ -205,13 +232,6 @@ def set_trace(
     """Set breakpoint at current location, or a specified frame"""
     if frame is None:
         frame = _frame().f_back
-    if term_size is None:
-        try:
-            # Getting terminal size
-            s = struct.unpack("hh", fcntl.ioctl(1, termios.TIOCGWINSZ, "1234"))
-            term_size = (s[1], s[0])
-        except Exception:
-            term_size = (80, 24)
 
     return debugger(
         term_size=term_size, host=host, port=port, reverse=reverse