Merge tag 'upstream/1.14.0'

Upstream version 1.14.0

30 files changed, 287 insertions, 237 deletions

diff --git a/sites/_shared_static/logo.png b/sites/_shared_static/logo.png
deleted file mode 100644
index bc76697..0000000
--- a/sites/_shared_static/logo.png
+++ /dev/null
diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst
new file mode 100644
index 0000000..3b614a8
--- /dev/null
+++ b/sites/docs/api/agent.rst
@@ -0,0 +1,6 @@
+SSH Agents
+==========
+
+.. automodule:: paramiko.agent
+    :inherited-members:
+    :no-special-members:
diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst
new file mode 100644
index 0000000..54d87c5
--- /dev/null
+++ b/sites/docs/api/buffered_pipe.rst
@@ -0,0 +1,4 @@
+Buffered pipes
+==============
+
+.. automodule:: paramiko.buffered_pipe
diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst
new file mode 100644
index 0000000..e71526f
--- /dev/null
+++ b/sites/docs/api/channel.rst
@@ -0,0 +1,4 @@
+Channel
+=======
+
+.. automodule:: paramiko.channel
diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst
new file mode 100644
index 0000000..b201812
--- /dev/null
+++ b/sites/docs/api/client.rst
@@ -0,0 +1,5 @@
+Client
+======
+
+.. automodule:: paramiko.client
+    :member-order: bysource
diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst
new file mode 100644
index 0000000..afb004c
--- /dev/null
+++ b/sites/docs/api/config.rst
@@ -0,0 +1,5 @@
+Configuration
+=============
+
+.. automodule:: paramiko.config
+    :member-order: bysource
diff --git a/sites/docs/api/file.rst b/sites/docs/api/file.rst
new file mode 100644
index 0000000..199f3ec
--- /dev/null
+++ b/sites/docs/api/file.rst
@@ -0,0 +1,4 @@
+Buffered files
+==============
+
+.. automodule:: paramiko.file
diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst
new file mode 100644
index 0000000..770652f
--- /dev/null
+++ b/sites/docs/api/hostkeys.rst
@@ -0,0 +1,5 @@
+Host keys / ``known_hosts`` files
+=================================
+
+.. automodule:: paramiko.hostkeys
+    :member-order: bysource
diff --git a/sites/docs/api/keys.rst b/sites/docs/api/keys.rst
new file mode 100644
index 0000000..af7b58c
--- /dev/null
+++ b/sites/docs/api/keys.rst
@@ -0,0 +1,6 @@
+Key handling
+============
+
+.. automodule:: paramiko.pkey
+.. automodule:: paramiko.dsskey
+.. automodule:: paramiko.rsakey
diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst
new file mode 100644
index 0000000..8d531e0
--- /dev/null
+++ b/sites/docs/api/message.rst
@@ -0,0 +1,4 @@
+Message
+=======
+
+.. automodule:: paramiko.message
diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst
new file mode 100644
index 0000000..4089203
--- /dev/null
+++ b/sites/docs/api/packet.rst
@@ -0,0 +1,4 @@
+Packetizer
+==========
+
+.. automodule:: paramiko.packet
diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst
new file mode 100644
index 0000000..e480446
--- /dev/null
+++ b/sites/docs/api/pipe.rst
@@ -0,0 +1,4 @@
+Cross-platform pipe implementations
+===================================
+
+.. automodule:: paramiko.pipe
diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst
new file mode 100644
index 0000000..489b14e
--- /dev/null
+++ b/sites/docs/api/proxy.rst
@@ -0,0 +1,4 @@
+``ProxyCommand`` support
+========================
+
+.. automodule:: paramiko.proxy
diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst
new file mode 100644
index 0000000..ea85454
--- /dev/null
+++ b/sites/docs/api/server.rst
@@ -0,0 +1,5 @@
+Server implementation
+=====================
+
+.. automodule:: paramiko.server
+    :member-order: bysource
diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst
new file mode 100644
index 0000000..956eada
--- /dev/null
+++ b/sites/docs/api/sftp.rst
@@ -0,0 +1,13 @@
+SFTP
+====
+
+.. automodule:: paramiko.sftp
+.. automodule:: paramiko.sftp_client
+.. automodule:: paramiko.sftp_server
+.. automodule:: paramiko.sftp_attr
+.. automodule:: paramiko.sftp_file
+    :inherited-members:
+    :no-special-members:
+    :show-inheritance:
+.. automodule:: paramiko.sftp_handle
+.. automodule:: paramiko.sftp_si
diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst
new file mode 100644
index 0000000..64872dc
--- /dev/null
+++ b/sites/docs/api/ssh_exception.rst
@@ -0,0 +1,4 @@
+Exceptions
+==========
+
+.. automodule:: paramiko.ssh_exception
diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst
new file mode 100644
index 0000000..7c9d9fd
--- /dev/null
+++ b/sites/docs/api/transport.rst
@@ -0,0 +1,5 @@
+Transport
+=========
+
+.. automodule:: paramiko.transport
+    :member-order: bysource
diff --git a/sites/docs/conf.py b/sites/docs/conf.py
index 0c7ffe5..5674fed 100644
--- a/sites/docs/conf.py
+++ b/sites/docs/conf.py
@@ -1,4 +1,16 @@
 # Obtain shared config values
 import os, sys
 sys.path.append(os.path.abspath('..'))
+sys.path.append(os.path.abspath('../..'))
 from shared_conf import *
+
+# Enable autodoc, intersphinx
+extensions.extend(['sphinx.ext.autodoc'])
+
+# Autodoc settings
+autodoc_default_flags = ['members', 'special-members']
+
+# Sister-site links to WWW
+html_theme_options['extra_nav_links'] = {
+    "Main website": 'http://www.paramiko.org',
+}
diff --git a/sites/docs/index.rst b/sites/docs/index.rst
index 08b3432..f336b39 100644
--- a/sites/docs/index.rst
+++ b/sites/docs/index.rst
@@ -1,6 +1,72 @@
+====================================
 Welcome to Paramiko's documentation!
 ====================================
 
 This site covers Paramiko's usage & API documentation. For basic info on what
 Paramiko is, including its public changelog & how the project is maintained,
-please see `the main website <http://paramiko.org>`_.
+please see `the main project website <http://paramiko.org>`_.
+
+
+API documentation
+=================
+
+The high-level client API starts with creation of an `.SSHClient` object. For
+more direct control, pass a socket (or socket-like object) to a `.Transport`,
+and use `start_server <.Transport.start_server>` or `start_client
+<.Transport.start_client>` to negotiate with the remote host as either a server
+or client.
+
+As a client, you are responsible for authenticating using a password or private
+key, and checking the server's host key. (Key signature and verification is
+done by paramiko, but you will need to provide private keys and check that the
+content of a public key matches what you expected to see.)
+
+As a server, you are responsible for deciding which users, passwords, and keys
+to allow, and what kind of channels to allow.
+
+Once you have finished, either side may request flow-controlled `channels
+<.Channel>` to the other side, which are Python objects that act like sockets,
+but send and receive data over the encrypted session.
+
+For details, please see the following tables of contents (which are organized
+by area of interest.)
+
+
+Core SSH protocol classes
+-------------------------
+
+.. toctree::
+    api/channel
+    api/client
+    api/message
+    api/packet
+    api/transport
+
+
+Authentication & keys
+---------------------
+
+.. toctree::
+    api/agent
+    api/hostkeys
+    api/keys
+
+
+Other primary functions
+-----------------------
+
+.. toctree::
+    api/config
+    api/proxy
+    api/server
+    api/sftp
+
+
+Miscellany
+----------
+
+.. toctree::
+    api/buffered_pipe
+    api/file
+    api/pipe
+    api/ssh_exception
diff --git a/sites/shared_conf.py b/sites/shared_conf.py
index 86ecdfe..6990838 100644
--- a/sites/shared_conf.py
+++ b/sites/shared_conf.py
@@ -1,15 +1,12 @@
 from datetime import datetime
-import os
-import sys
 
 import alabaster
 
 
 # Alabaster theme + mini-extension
 html_theme_path = [alabaster.get_path()]
-extensions = ['alabaster']
+extensions = ['alabaster', 'sphinx.ext.intersphinx']
 # Paths relative to invoking conf.py - not this shared file
-html_static_path = ['../_shared_static']
 html_theme = 'alabaster'
 html_theme_options = {
     'description': "A Python implementation of SSHv2.",
@@ -17,9 +14,7 @@ html_theme_options = {
     'github_repo': 'paramiko',
     'gittip_user': 'bitprophet',
     'analytics_id': 'UA-18486793-2',
-
-    'link': '#3782BE',
-    'link_hover': '#3782BE',
+    'travis_button': True,
 }
 html_sidebars = {
     '**': [
@@ -30,10 +25,15 @@ html_sidebars = {
     ]
 }
 
+# Everything intersphinx's to Python
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/2.6', None),
+}
+
 # Regular settings
-project = u'Paramiko'
+project = 'Paramiko'
 year = datetime.now().year
-copyright = u'%d Jeff Forcier' % year
+copyright = '%d Jeff Forcier' % year
 master_doc = 'index'
 templates_path = ['_templates']
 exclude_trees = ['_build']
diff --git a/sites/www/blog.py b/sites/www/blog.py
deleted file mode 100644
index 3b129eb..0000000
--- a/sites/www/blog.py
+++ /dev/null
@@ -1,140 +0,0 @@
-from collections import namedtuple
-from datetime import datetime
-import time
-import email.utils
-
-from sphinx.util.compat import Directive
-from docutils import nodes
-
-
-class BlogDateDirective(Directive):
-    """
-    Used to parse/attach date info to blog post documents.
-
-    No nodes generated, since none are needed.
-    """
-    has_content = True
-
-    def run(self):
-        # Tag parent document with parsed date value.
-        self.state.document.blog_date = datetime.strptime(
-            self.content[0], "%Y-%m-%d"
-        )
-        # Don't actually insert any nodes, we're already done.
-        return []
-
-class blog_post_list(nodes.General, nodes.Element):
-    pass
-
-class BlogPostListDirective(Directive):
-    """
-    Simply spits out a 'blog_post_list' temporary node for replacement.
-
-    Gets replaced at doctree-resolved time - only then will all blog post
-    documents be written out (& their date directives executed).
-    """
-    def run(self):
-        return [blog_post_list('')]
-
-
-Post = namedtuple('Post', 'name doc title date opener')
-
-def get_posts(app):
-    # Obtain blog posts
-    post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs)
-    posts = map(lambda x: (x, app.env.get_doctree(x)), post_names)
-    # Obtain common data used for list page & RSS
-    data = []
-    for post, doc in sorted(posts, key=lambda x: x[1].blog_date, reverse=True):
-        # Welp. No "nice" way to get post title. Thanks Sphinx.
-        title = doc[0][0][0]
-        # Date. This may or may not end up reflecting the required
-        # *input* format, but doing it here gives us flexibility.
-        date = doc.blog_date
-        # 1st paragraph as opener. TODO: allow a role or something marking
-        # where to actually pull from?
-        opener = doc.traverse(nodes.paragraph)[0]
-        data.append(Post(post, doc, title, date, opener))
-    return data
-
-def replace_blog_post_lists(app, doctree, fromdocname):
-    """
-    Replace blog_post_list nodes with ordered list-o-links to posts.
-    """
-    # Obtain blog posts
-    post_names = filter(lambda x: x.startswith('blog/'), app.env.found_docs)
-    posts = map(lambda x: (x, app.env.get_doctree(x)), post_names)
-    # Build "list" of links/etc
-    post_links = []
-    for post, doc, title, date, opener in get_posts(app):
-        # Link itself
-        uri = app.builder.get_relative_uri(fromdocname, post)
-        link = nodes.reference('', '', refdocname=post, refuri=uri)
-        # Title, bolded. TODO: use 'topic' or something maybe?
-        link.append(nodes.strong('', title))
-        date = date.strftime("%Y-%m-%d")
-        # Meh @ not having great docutils nodes which map to this.
-        html = '<div class="timestamp"><span>%s</span></div>' % date
-        timestamp = nodes.raw(text=html, format='html')
-        # NOTE: may group these within another element later if styling
-        # necessitates it
-        group = [timestamp, nodes.paragraph('', '', link), opener]
-        post_links.extend(group)
-
-    # Replace temp node(s) w/ expanded list-o-links
-    for node in doctree.traverse(blog_post_list):
-        node.replace_self(post_links)
-
-def rss_timestamp(timestamp):
-    # Use horribly inappropriate module for its magical daylight-savings-aware
-    # timezone madness. Props to Tinkerer for the idea.
-    return email.utils.formatdate(
-        time.mktime(timestamp.timetuple()),
-        localtime=True
-    )
-
-def generate_rss(app):
-    # Meh at having to run this subroutine like 3x per build. Not worth trying
-    # to be clever for now tho.
-    posts_ = get_posts(app)
-    # LOL URLs
-    root = app.config.rss_link
-    if not root.endswith('/'):
-        root += '/'
-    # Oh boy
-    posts = [
-        (
-            root + app.builder.get_target_uri(x.name),
-            x.title,
-            str(x.opener[0]), # Grab inner text element from paragraph
-            rss_timestamp(x.date),
-        )
-        for x in posts_
-    ]
-    location = 'blog/rss.xml'
-    context = {
-        'title': app.config.project,
-        'link': root,
-        'atom': root + location,
-        'description': app.config.rss_description,
-        # 'posts' is sorted by date already
-        'date': rss_timestamp(posts_[0].date),
-        'posts': posts,
-    }
-    yield (location, context, 'rss.xml')
-
-def setup(app):
-    # Link in RSS feed back to main website, e.g. 'http://paramiko.org'
-    app.add_config_value('rss_link', None, '')
-    # Ditto for RSS description field
-    app.add_config_value('rss_description', None, '')
-    # Interprets date metadata in blog post documents
-    app.add_directive('date', BlogDateDirective)
-    # Inserts blog post list node (in e.g. a listing page) for replacement
-    # below
-    app.add_node(blog_post_list)
-    app.add_directive('blog-posts', BlogPostListDirective)
-    # Performs abovementioned replacement
-    app.connect('doctree-resolved', replace_blog_post_lists)
-    # Generates RSS page from whole cloth at page generation step
-    app.connect('html-collect-pages', generate_rss)
diff --git a/sites/www/blog.rst b/sites/www/blog.rst
deleted file mode 100644
index af9651e..0000000
--- a/sites/www/blog.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-====
-Blog
-====
-
-.. blog-posts directive gets replaced with an ordered list of blog posts.
-
-.. blog-posts::
-
-
-.. The following toctree ensures blog posts get processed.
-
-.. toctree::
-    :hidden:
-    :glob:
-
-    blog/*
diff --git a/sites/www/blog/first-post.rst b/sites/www/blog/first-post.rst
deleted file mode 100644
index 7b07507..0000000
--- a/sites/www/blog/first-post.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-===========
-First post!
-===========
-
-A blog post.
-
-.. date:: 2013-12-04
diff --git a/sites/www/blog/second-post.rst b/sites/www/blog/second-post.rst
deleted file mode 100644
index c4463f3..0000000
--- a/sites/www/blog/second-post.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-===========
-Another one
-===========
-
-.. date:: 2013-12-05
-
-Indeed!
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst
index ffacf6e..f8a4d2c 100644
--- a/sites/www/changelog.rst
+++ b/sites/www/changelog.rst
@@ -2,9 +2,70 @@
 Changelog
 =========
 
+* :release:`1.14.0 <2014-05-07>`
+* :release:`1.13.1 <2014-05-07>`
+* :release:`1.12.4 <2014-05-07>`
+* :release:`1.11.6 <2014-05-07>`
+* :bug:`-` `paramiko.file.BufferedFile.read` incorrectly returned text strings
+  after the Python 3 migration, despite bytes being more appropriate for file
+  contents (which may be binary or of an unknown encoding.) This has been
+  addressed.
+
+  .. note::
+      `paramiko.file.BufferedFile.readline` continues to return strings, not
+      bytes, as "lines" only make sense for textual data. It assumes UTF-8 by
+      default.
+
+  This should fix `this issue raised on the Obnam mailing list
+  <http://comments.gmane.org/gmane.comp.sysutils.backup.obnam/252>`_.  Thanks
+  to Antoine Brenner for the patch.
+* :bug:`-` Added self.args for exception classes. Used for unpickling. Related
+  to (`Fabric #986 <https://github.com/fabric/fabric/issues/986>`_, `Fabric
+  #714 <https://github.com/fabric/fabric/issues/714>`_). Thanks to Alex
+  Plugaru.
+* :bug:`-` Fix logging error in sftp_client for filenames containing the '%'
+  character. Thanks to Antoine Brenner.
+* :bug:`308` Fix regression in dsskey.py that caused sporadic signature 
+  verification failures. Thanks to Chris Rose.
+* :support:`299` Use deterministic signatures for ECDSA keys for improved
+  security. Thanks to Alex Gaynor.
+* :support:`297` Replace PyCrypto's ``Random`` with `os.urandom` for improved
+  speed and security. Thanks again to Alex.
+* :support:`295` Swap out a bunch of PyCrypto hash functions with use of
+  `hashlib`. Thanks to Alex Gaynor.
+* :support:`290` (also :issue:`292`) Add support for building universal
+  (Python 2+3 compatible) wheel files during the release process. Courtesy of
+  Alex Gaynor.
+* :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks
+  to Alex Gaynor for catch & patch.
+* :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if
+  type(x) is str/if isinstance(x, basestring)/g``.) Thanks to ``@ksamuel`` for
+  the report.
+* :release:`1.13.0 <2014-03-13>`
+* :release:`1.12.3 <2014-03-13>`
+* :release:`1.11.5 <2014-03-13>`
+* :release:`1.10.7 <2014-03-13>`
+* :feature:`16` **Python 3 support!** Our test suite passes under Python 3, and
+  it (& Fabric's test suite) continues to pass under Python 2. **Python 2.5 is
+  no longer supported with this change!**
+  
+  The merged code was built on many contributors' efforts, both code &
+  feedback. In no particular order, we thank Daniel Goertzen, Ivan Kolodyazhny,
+  Tomi Pieviläinen, Jason R. Coombs, Jan N. Schulze, ``@Lazik``, Dorian Pula,
+  Scott Maxwell, Tshepang Lekhonkhobe, Aaron Meurer, and Dave Halter.
+* :support:`256 backported` Convert API documentation to Sphinx, yielding a new
+  API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for
+  the initial conversion work.
+* :bug:`-` Use constant-time hash comparison operations where possible, to
+  protect against `timing-based attacks
+  <http://codahale.com/a-lesson-in-timing-attacks/>`_. Thanks to Alex Gaynor
+  for the patch.
 * :release:`1.12.2 <2014-02-14>`
 * :release:`1.11.4 <2014-02-14>`
 * :release:`1.10.6 <2014-02-14>`
+* :feature:`58` Allow client code to access the stored SSH server banner via
+  `Transport.get_banner <paramiko.transport.Transport.get_banner>`. Thanks to
+  ``@Jhoanor`` for the patch.
 * :bug:`252` (`Fabric #1020 <https://github.com/fabric/fabric/issues/1020>`_)
   Enhanced the implementation of ``ProxyCommand`` to avoid a deadlock/hang
   condition that frequently occurs at ``Transport`` shutdown time. Thanks to
@@ -29,10 +90,10 @@ Changelog
 * :release:`1.12.0 <2013-09-27>`
 * :release:`1.11.2 <2013-09-27>`
 * :release:`1.10.4 <2013-09-27>`
-* :feature:`152` Add tentative support for ECDSA keys. *This adds the ecdsa
-  module as a new dependency of Paramiko.* The module is available at
-  [warner/python-ecdsa on Github](https://github.com/warner/python-ecdsa) and
-  [ecdsa on PyPI](https://pypi.python.org/pypi/ecdsa).
+* :feature:`152` Add tentative support for ECDSA keys. **This adds the ecdsa
+  module as a new dependency of Paramiko.** The module is available at
+  `warner/python-ecdsa on Github <https://github.com/warner/python-ecdsa>`_ and
+  `ecdsa on PyPI <https://pypi.python.org/pypi/ecdsa>`_.
 
     * Note that you might still run into problems with key negotiation --
       Paramiko picks the first key that the server offers, which might not be
diff --git a/sites/www/conf.py b/sites/www/conf.py
index 481acdf..bdb5929 100644
--- a/sites/www/conf.py
+++ b/sites/www/conf.py
@@ -6,15 +6,10 @@ from os.path import abspath, join, dirname
 sys.path.append(abspath(join(dirname(__file__), '..')))
 from shared_conf import *
 
-# Local blog extension
-sys.path.append(abspath('.'))
-extensions.append('blog')
-rss_link = 'http://paramiko.org'
-rss_description = 'Paramiko project news'
-
 # Releases changelog extension
 extensions.append('releases')
-releases_release_uri = "https://github.com/paramiko/paramiko/tree/%s"
+# Paramiko 1.x tags start with 'v'. Meh.
+releases_release_uri = "https://github.com/paramiko/paramiko/tree/v%s"
 releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s"
 
 # Intersphinx for referencing API/usage docs
@@ -24,10 +19,8 @@ extensions.append('sphinx.ext.intersphinx')
 target = join(dirname(__file__), '..', 'docs', '_build')
 if os.environ.get('READTHEDOCS') == 'True':
     # TODO: switch to docs.paramiko.org post go-live of sphinx API docs
-    target = 'http://paramiko-docs.readthedocs.org/en/latest/'
-#intersphinx_mapping = {
-#    'docs': (target, None),
-#}
+    target = 'http://docs.paramiko.org/en/latest/'
+intersphinx_mapping['docs'] = (target, None)
 
 # Sister-site links to API docs
 html_theme_options['extra_nav_links'] = {
diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst
index 2b752cc..634c2b2 100644
--- a/sites/www/contributing.rst
+++ b/sites/www/contributing.rst
@@ -17,3 +17,6 @@ How to submit bug reports or new code
 
 Please see `this project-agnostic contribution guide
 <http://contribution-guide.org>`_ - we follow it explicitly.
+
+Our current changelog is located in ``sites/www/changelog.rst`` - the top
+level files like ``ChangeLog.*`` and ``NEWS`` are historical only.
diff --git a/sites/www/faq.rst b/sites/www/faq.rst
new file mode 100644
index 0000000..a7e8001
--- /dev/null
+++ b/sites/www/faq.rst
@@ -0,0 +1,9 @@
+===================================
+Frequently Asked/Answered Questions
+===================================
+
+Which version should I use? I see multiple active releases.
+===========================================================
+
+Please see :ref:`the installation docs <release-lines>` which have an explicit
+section about this topic.
diff --git a/sites/www/index.rst b/sites/www/index.rst
index 7fefedd..1b60970 100644
--- a/sites/www/index.rst
+++ b/sites/www/index.rst
@@ -1,7 +1,7 @@
 Welcome to Paramiko!
 ====================
 
-Paramiko is a Python (2.5+) implementation of the SSHv2 protocol [#]_,
+Paramiko is a Python (2.6+, 3.3+) implementation of the SSHv2 protocol [#]_,
 providing both client and server functionality. While it leverages a Python C
 extension for low level cryptography (`PyCrypto <http://pycrypto.org>`_),
 Paramiko itself is a pure Python interface around SSH networking concepts.
@@ -11,19 +11,17 @@ contribution guidelines, development roadmap, news/blog, and so forth. Detailed
 usage and API documentation can be found at our code documentation site,
 `docs.paramiko.org <http://docs.paramiko.org>`_.
 
+Please see the sidebar to the left to begin.
+
 .. toctree::
+    :hidden:
+
     changelog
+    FAQs <faq>
     installing
     contributing
     contact
 
-.. Hide blog in hidden toctree for now (to avoid warnings.)
-
-.. toctree::
-    :hidden:
-
-    blog
-
 
 .. rubric:: Footnotes
 
diff --git a/sites/www/installing.rst b/sites/www/installing.rst
index 0d4dc1a..a28ce6c 100644
--- a/sites/www/installing.rst
+++ b/sites/www/installing.rst
@@ -2,10 +2,12 @@
 Installing
 ==========
 
+.. _paramiko-itself:
+
 Paramiko itself
 ===============
 
-The recommended way to get Invoke is to **install the latest stable release**
+The recommended way to get Paramiko is to **install the latest stable release**
 via `pip <http://pip-installer.org>`_::
 
     $ pip install paramiko
@@ -14,50 +16,44 @@ via `pip <http://pip-installer.org>`_::
     Users who want the bleeding edge can install the development version via
     ``pip install paramiko==dev``.
 
-We currently support **Python 2.5/2.6/2.7**, with support for Python 3 coming
-soon. Users on Python 2.4 or older are urged to upgrade. Paramiko *may* work on
-Python 2.4 still, but there is no longer any support guarantee.
+We currently support **Python 2.6, 2.7 and 3.3** (Python **3.2** should also
+work but has a less-strong compatibility guarantee from us.) Users on Python
+2.5 or older are urged to upgrade.
 
-Paramiko has two dependencies: the pure-Python ECDSA module `ecdsa`, and the
-PyCrypto C extension. `ecdsa` is easily installable from wherever you
+Paramiko has two dependencies: the pure-Python ECDSA module ``ecdsa``, and the
+PyCrypto C extension. ``ecdsa`` is easily installable from wherever you
 obtained Paramiko's package; PyCrypto may require more work. Read on for
 details.
 
-PyCrypto
-========
-
-`PyCrypto <https://www.dlitz.net/software/pycrypto/>`_  provides the low-level
-(C-based) encryption algorithms we need to implement the SSH protocol. There
-are a couple gotchas associated with installing PyCrypto: its compatibility
-with Python's package tools, and the fact that it is a C-based extension.
+.. _release-lines:
 
-.. _pycrypto-and-pip:
+Release lines
+-------------
 
-Possible gotcha on older Python and/or pip versions
----------------------------------------------------
+Users desiring stability may wish to pin themselves to a specific release line
+once they first start using Paramiko; to assist in this, we guarantee bugfixes
+for at least the last 2-3 releases including the latest stable one. This currently means Paramiko **1.11** through **1.13**.
 
-We strongly recommend using ``pip`` to as it is newer and generally better than
-``easy_install``. However, a combination of bugs in specific (now rather old)
-versions of Python, ``pip`` and PyCrypto can prevent installation of PyCrypto.
-Specifically:
+If you're unsure which version to install, we have suggestions:
 
-* Python = 2.5.x
-* PyCrypto >= 2.1 (required for most modern versions of Paramiko)
-* ``pip`` < 0.8.1
+* **Completely new users** should always default to the **latest stable
+  release** (as above, whatever is newest / whatever shows up with ``pip
+  install paramiko``.)
+* **Users upgrading from a much older version** (e.g. the 1.7.x line) should
+  probably get the **oldest actively supported line** (see the paragraph above
+  this list for what that currently is.)
+* **Everybody else** is hopefully already "on" a given version and can
+  carefully upgrade to whichever version they care to, when their release line
+  stops being supported.
 
-When all three criteria are met, you may encounter ``No such file or
-directory`` IOErrors when trying to ``pip install paramiko`` or ``pip install
-PyCrypto``.
 
-The fix is to make sure at least one of the above criteria is not met, by doing
-the following (in order of preference):
-
-* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``.
-* Upgrade to Python 2.6 or above.
-* Downgrade to Paramiko 1.7.6 or 1.7.7, which do not require PyCrypto >= 2.1,
-  and install PyCrypto 2.0.1 (the oldest version on PyPI which works with
-  Paramiko 1.7.6/1.7.7)
+PyCrypto
+========
 
+`PyCrypto <https://www.dlitz.net/software/pycrypto/>`_  provides the low-level
+(C-based) encryption algorithms we need to implement the SSH protocol. There
+are a couple gotchas associated with installing PyCrypto: its compatibility
+with Python's package tools, and the fact that it is a C-based extension.
 
 C extension
 -----------