Move to 'inv sites' style doc nitpicking.

Existing just-warnings setup was old and not as rigorous as my usual.

Required a lot of stupid little changes, but now same tooling for all
projects, toot toot.

.travis.yml

@@ -20,11 +20,8 @@ install:
 script:
   # Main tests, w/ coverage!
   - inv test --coverage
-  # Ensure documentation & invoke pipeline run OK.
-  # Run 'docs' first since its objects.inv is referred to by 'www'.
-  # Also force warnings to be errors since most of them tend to be actual
-  # problems.
-  - invoke docs -o -W www -o -W
+  # Ensure documentation builds, both sites, maxxed nitpicking
+  - inv sites
   # flake8 is now possible!
   - flake8
 notifications:

paramiko/agent.py

@@ -253,7 +253,7 @@ class AgentServerProxy(AgentSSH):
     """
     :param .Transport t: Transport used for SSH Agent communication forwarding
 
-    :raises SSHException: mostly if we lost the agent
+    :raises: `.SSHException` -- mostly if we lost the agent
     """
     def __init__(self, t):
         AgentSSH.__init__(self)
@@ -347,7 +347,7 @@ class Agent(AgentSSH):
     opened, if one is running. If no agent is running, initialization will
     succeed, but `get_keys` will return an empty tuple.
 
-    :raises SSHException:
+    :raises: `.SSHException` --
         if an SSH agent is found, but speaks an incompatible protocol
     """
     def __init__(self):

paramiko/buffered_pipe.py

@@ -90,7 +90,7 @@ def feed(self, data):
         Feed new data into this pipe.  This method is assumed to be called
         from a separate thread, so synchronization is done.
 
-        :param data: the data to add, as a `str` or `bytes`
+        :param data: the data to add, as a ``str`` or ``bytes``
         """
         self._lock.acquire()
         try:
@@ -134,11 +134,11 @@ def read(self, nbytes, timeout=None):
         :param int nbytes: maximum number of bytes to read
         :param float timeout:
             maximum seconds to wait (or ``None``, the default, to wait forever)
-        :return: the read data, as a `bytes`
+        :return: the read data, as a ``str`` or ``bytes``
 
-        :raises PipeTimeout:
-            if a timeout was specified and no data was ready before that
-            timeout
+        :raises:
+            `.PipeTimeout` -- if a timeout was specified and no data was ready
+            before that timeout
         """
         out = bytes()
         self._lock.acquire()

paramiko/channel.py

@@ -46,8 +46,9 @@ def open_only(func):
     """
     Decorator for `.Channel` methods which performs an openness check.
 
-    :raises SSHException:
-        If the wrapped method is called on an unopened `.Channel`.
+    :raises:
+        `.SSHException` -- If the wrapped method is called on an unopened
+        `.Channel`.
     """
     @wraps(func)
     def _check(self, *args, **kwds):
@@ -165,8 +166,9 @@ def get_pty(self, term='vt100', width=80, height=24, width_pixels=0,
         :param int width_pixels: width (in pixels) of the terminal screen
         :param int height_pixels: height (in pixels) of the terminal screen
 
-        :raises SSHException:
-            if the request was rejected or the channel was closed
+        :raises:
+            `.SSHException` -- if the request was rejected or the channel was
+            closed
         """
         m = Message()
         m.add_byte(cMSG_CHANNEL_REQUEST)
@@ -197,7 +199,8 @@ def invoke_shell(self):
         When the shell exits, the channel will be closed and can't be reused.
         You must open a new channel if you wish to open another shell.
 
-        :raises SSHException: if the request was rejected or the channel was
+        :raises:
+            `.SSHException` -- if the request was rejected or the channel was
             closed
         """
         m = Message()
@@ -222,7 +225,8 @@ def exec_command(self, command):
 
         :param str command: a shell command to execute.
 
-        :raises SSHException: if the request was rejected or the channel was
+        :raises:
+            `.SSHException` -- if the request was rejected or the channel was
             closed
         """
         m = Message()
@@ -247,8 +251,9 @@ def invoke_subsystem(self, subsystem):
 
         :param str subsystem: name of the subsystem being requested.
 
-        :raises SSHException:
-            if the request was rejected or the channel was closed
+        :raises:
+            `.SSHException` -- if the request was rejected or the channel was
+            closed
         """
         m = Message()
         m.add_byte(cMSG_CHANNEL_REQUEST)
@@ -271,8 +276,9 @@ def resize_pty(self, width=80, height=24, width_pixels=0, height_pixels=0):
         :param int width_pixels: new width (in pixels) of the terminal screen
         :param int height_pixels: new height (in pixels) of the terminal screen
 
-        :raises SSHException:
-            if the request was rejected or the channel was closed
+        :raises:
+            `.SSHException` -- if the request was rejected or the channel was
+            closed
         """
         m = Message()
         m.add_byte(cMSG_CHANNEL_REQUEST)
@@ -313,11 +319,11 @@ def recv_exit_status(self):
             `.Transport` or session's ``window_size`` (e.g. that set by the
             ``default_window_size`` kwarg for `.Transport.__init__`) will cause
             `.recv_exit_status` to hang indefinitely if it is called prior to a
-            sufficiently large `~Channel..read` (or if there are no threads
-            calling `~Channel.read` in the background).
+            sufficiently large `.Channel.recv` (or if there are no threads
+            calling `.Channel.recv` in the background).
 
             In these cases, ensuring that `.recv_exit_status` is called *after*
-            `~Channel.read` (or, again, using threads) can avoid the hang.
+            `.Channel.recv` (or, again, using threads) can avoid the hang.
 
         :return: the exit code (as an `int`) of the process on the server.
 
@@ -391,8 +397,8 @@ def request_x11(
             if True, only a single x11 connection will be forwarded (by
             default, any number of x11 connections can arrive over this
             session)
-        :param function handler:
-            an optional handler to use for incoming X11 connections
+        :param handler:
+            an optional callable handler to use for incoming X11 connections
         :return: the auth_cookie used
         """
         if auth_protocol is None:
@@ -421,8 +427,9 @@ def request_forward_agent(self, handler):
         Request for a forward SSH Agent on this channel.
         This is only valid for an ssh-agent from OpenSSH !!!
 
-        :param function handler:
-            a required handler to use for incoming SSH Agent connections
+        :param handler:
+            a required callable handler to use for incoming SSH Agent
+            connections
 
         :return: True if we are ok, else False
             (at that time we always return ok)
@@ -613,7 +620,7 @@ def recv(self, nbytes):
         length zero is returned, the channel stream has closed.
 
         :param int nbytes: maximum number of bytes to read.
-        :return: received data, as a `bytes`
+        :return: received data, as a ``str``/``bytes``.
 
         :raises socket.timeout:
             if no data is ready before the timeout set by `settimeout`.

paramiko/client.py

@@ -91,7 +91,7 @@ def load_system_host_keys(self, filename=None):
 
         :param str filename: the filename to read, or ``None``
 
-        :raises IOError:
+        :raises: ``IOError`` --
             if a filename was provided and the file could not be read
         """
         if filename is None:
@@ -118,7 +118,7 @@ def load_host_keys(self, filename):
 
         :param str filename: the filename to read
 
-        :raises IOError: if the filename could not be read
+        :raises: ``IOError`` -- if the filename could not be read
         """
         self._host_keys_filename = filename
         self._host_keys.load(filename)
@@ -131,7 +131,7 @@ def save_host_keys(self, filename):
 
         :param str filename: the filename to save to
 
-        :raises IOError: if the file could not be written
+        :raises: ``IOError`` -- if the file could not be written
         """
 
         # update local host keys from file (in case other SSH clients
@@ -282,10 +282,12 @@ def connect(
         :param float banner_timeout: an optional timeout (in seconds) to wait
             for the SSH banner to be presented.
 
-        :raises BadHostKeyException: if the server's host key could not be
+        :raises:
+            `.BadHostKeyException` -- if the server's host key could not be
             verified
-        :raises AuthenticationException: if authentication failed
-        :raises SSHException: if there was any other error connecting or
+        :raises: `.AuthenticationException` -- if authentication failed
+        :raises:
+            `.SSHException` -- if there was any other error connecting or
             establishing an SSH session
         :raises socket.error: if a socket error occurred while connecting
 
@@ -416,12 +418,12 @@ def exec_command(self, command, bufsize=-1, timeout=None, get_pty=False):
             interpreted the same way as by the built-in ``file()`` function in
             Python
         :param int timeout:
-            set command's channel timeout. See `Channel.settimeout`.settimeout
+            set command's channel timeout. See `.Channel.settimeout`
         :return:
             the stdin, stdout, and stderr of the executing command, as a
             3-tuple
 
-        :raises SSHException: if the server fails to execute the command
+        :raises: `.SSHException` -- if the server fails to execute the command
         """
         chan = self._transport.open_session(timeout=timeout)
         if get_pty:
@@ -448,7 +450,7 @@ def invoke_shell(self, term='vt100', width=80, height=24, width_pixels=0,
         :param int height_pixels: the height (in pixels) of the terminal window
         :return: a new `.Channel` connected to the remote shell
 
-        :raises SSHException: if the server fails to invoke a shell
+        :raises: `.SSHException` -- if the server fails to invoke a shell
         """
         chan = self._transport.open_session()
         chan.get_pty(term, width, height, width_pixels, height_pixels)

paramiko/dsskey.py

@@ -208,7 +208,7 @@ def generate(bits=1024, progress_func=None):
         generate a new host key or authentication key.
 
         :param int bits: number of bits the generated key should be.
-        :param function progress_func: Unused
+        :param progress_func: Unused
         :return: new `.DSSKey` private key
         """
         numbers = dsa.generate_private_key(

paramiko/ecdsakey.py

@@ -231,7 +231,7 @@ def generate(cls, curve=ec.SECP256R1(), progress_func=None, bits=None):
         Generate a new private ECDSA key.  This factory function can be used to
         generate a new host key or authentication key.
 
-        :param function progress_func: Not used for this type of key.
+        :param progress_func: Not used for this type of key.
         :returns: A new private key (`.ECDSAKey`) object
         """
         if bits is not None:

paramiko/file.py

@@ -67,7 +67,7 @@ def __iter__(self):
         file.  This iterator happens to return the file itself, since a file is
         its own iterator.
 
-        :raises ValueError: if the file is closed.
+        :raises: ``ValueError`` -- if the file is closed.
         """
         if self._closed:
             raise ValueError('I/O operation on closed file')
@@ -93,10 +93,10 @@ def flush(self):
         def next(self):
             """
             Returns the next line from the input, or raises
-            `~exceptions.StopIteration` when EOF is hit.  Unlike Python file
+            ``StopIteration`` when EOF is hit.  Unlike Python file
             objects, it's okay to mix calls to `next` and `readline`.
 
-            :raises StopIteration: when the end of the file is reached.
+            :raises: ``StopIteration`` -- when the end of the file is reached.
 
             :returns: a line (`str`) read from the file.
             """
@@ -107,11 +107,11 @@ def next(self):
     else:
         def __next__(self):
             """
-            Returns the next line from the input, or raises `.StopIteration`
+            Returns the next line from the input, or raises ``StopIteration``
             when EOF is hit.  Unlike python file objects, it's okay to mix
             calls to `.next` and `.readline`.
 
-            :raises StopIteration: when the end of the file is reached.
+            :raises: ``StopIteration`` -- when the end of the file is reached.
 
             :returns: a line (`str`) read from the file.
             """
@@ -152,8 +152,8 @@ def seekable(self):
 
     def readinto(self, buff):
         """
-        Read up to ``len(buff)`` bytes into :class:`bytearray` *buff* and
-        return the number of bytes read.
+        Read up to ``len(buff)`` bytes into ``bytearray`` *buff* and return the
+        number of bytes read.
 
         :returns:
             The number of bytes read.
@@ -368,7 +368,7 @@ def seek(self, offset, whence=0):
             type of movement: 0 = absolute; 1 = relative to the current
             position; 2 = relative to the end of the file.
 
-        :raises IOError: if the file doesn't support random access.
+        :raises: ``IOError`` -- if the file doesn't support random access.
         """
         raise IOError('File does not support seeking.')
 
@@ -389,7 +389,7 @@ def write(self, data):
         written yet.  (Use `flush` or `close` to force buffered data to be
         written out.)
 
-        :param str/bytes data: data to write
+        :param data: ``str``/``bytes`` data to write
         """
         data = b(data)
         if self._closed:
@@ -423,7 +423,7 @@ def writelines(self, sequence):
         name is intended to match `readlines`; `writelines` does not add line
         separators.)
 
-        :param iterable sequence: an iterable sequence of strings.
+        :param sequence: an iterable sequence of strings.
         """
         for line in sequence:
             self.write(line)

paramiko/hostkeys.py

@@ -90,7 +90,7 @@ def load(self, filename):
 
         :param str filename: name of the file to read host keys from
 
-        :raises IOError: if there was an error reading the file
+        :raises: ``IOError`` -- if there was an error reading the file
         """
         with open(filename, 'r') as f:
             for lineno, line in enumerate(f, 1):
@@ -118,7 +118,7 @@ def save(self, filename):
 
         :param str filename: name of the file to write
 
-        :raises IOError: if there was an error writing the file
+        :raises: ``IOError`` -- if there was an error writing the file
 
         .. versionadded:: 1.6.1
         """

paramiko/kex_gss.py

@@ -108,7 +108,7 @@ def parse_next(self, ptype, m):
         """
         Parse the next packet.
 
-        :param char ptype: The type of the incoming packet
+        :param ptype: The (string) type of the incoming packet
         :param `.Message` m: The paket content
         """
         if self.transport.server_mode and (ptype == MSG_KEXGSS_INIT):
@@ -345,7 +345,7 @@ def parse_next(self, ptype, m):
         """
         Parse the next packet.
 
-        :param char ptype: The type of the incoming packet
+        :param ptype: The (string) type of the incoming packet
         :param `.Message` m: The paket content
         """
         if ptype == MSG_KEXGSS_GROUPREQ:

paramiko/packet.py

@@ -43,6 +43,9 @@ def compute_hmac(key, message, digest_class):
 
 
 class NeedRekeyException (Exception):
+    """
+    Exception indicating a rekey is needed.
+    """
     pass
 
 
@@ -253,8 +256,9 @@ def read_all(self, n, check_rekey=False):
         :param int n: number of bytes to read
         :return: the data read, as a `str`
 
-        :raises EOFError:
-            if the socket was closed before all the bytes could be read
+        :raises:
+            ``EOFError`` -- if the socket was closed before all the bytes could
+            be read
         """
         out = bytes()
         # handle over-reading from reading the banner line
@@ -413,8 +417,8 @@ def read_message(self):
         Only one thread should ever be in this function (no other locking is
         done).
 
-        :raises SSHException: if the packet is mangled
-        :raises NeedRekeyException: if the transport should rekey
+        :raises: `.SSHException` -- if the packet is mangled
+        :raises: `.NeedRekeyException` -- if the transport should rekey
         """
         header = self.read_all(self.__block_size_in, check_rekey=True)
         if self.__block_engine_in is not None: