Fix warnings when building the docs

It may be nice to make builds fail if new documentation generates warnings, to
avoid these sorts of problems slipping in in the future.

docs/index.rst

@@ -130,6 +130,5 @@ you.
    :maxdepth: 1
 
    dev/philosophy
-   dev/internals
    dev/todo
    dev/authors

docs/user/advanced.rst

@@ -300,7 +300,7 @@ Then, we can make a request using our Pizza Auth::
     >>> requests.get('http://pizzabin.org/admin', auth=PizzaAuth('kenneth'))
     <Response [200]>
 
-.. _streaming-requests
+.. _streaming-requests:
 
 Streaming Requests
 ------------------

requests/adapters.py

@@ -55,14 +55,16 @@ class HTTPAdapter(BaseAdapter):
 
     :param pool_connections: The number of urllib3 connection pools to cache.
     :param pool_maxsize: The maximum number of connections to save in the pool.
-    :param max_retries: The maximum number of retries each connection should attempt.
+    :param int max_retries: The maximum number of retries each connection
+        should attempt. Note, this applies only to failed connections and
+        timeouts, never to requests where the server returns a response.
     :param pool_block: Whether the connection pool should block for connections.
 
     Usage::
 
       >>> import requests
       >>> s = requests.Session()
-      >>> a = requests.adapters.HTTPAdapter()
+      >>> a = requests.adapters.HTTPAdapter(max_retries=3)
       >>> s.mount('http://', a)
     """
     __attrs__ = ['max_retries', 'config', '_pool_connections', '_pool_maxsize',

requests/models.py

@@ -526,7 +526,7 @@ class Response(object):
         self.headers = CaseInsensitiveDict()
 
         #: File-like object representation of response (for advanced usage).
-        #: Requires that ``stream=True` on the request.
+        #: Use of ``raw`` requires that ``stream=True`` be set on the request.
         # This requirement does not apply for use internally to Requests.
         self.raw = None
 

requests/sessions.py

@@ -256,7 +256,7 @@ class Session(SessionRedirectMixin):
         :class:`Session`.
 
         :param request: :class:`Request` instance to prepare with this
-        session's settings.
+            session's settings.
         """
         cookies = request.cookies or {}