Merge pull request psf#1832 from kevinburke/docs-warnings

Fix warnings when building the docs

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 @@ def __init__(self):
         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 @@ def prepare_request(self, request):
         :class:`Session`.
 
         :param request: :class:`Request` instance to prepare with this
-        session's settings.
+            session's settings.
         """
         cookies = request.cookies or {}