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.

diff --git a/docs/index.rst b/docs/index.rst
index 85e1172..4b0ecfd 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -130,6 +130,5 @@ you.
    :maxdepth: 1
 
    dev/philosophy
-   dev/internals
    dev/todo
    dev/authors

diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index 3ff66d5..a0565f2 100644 (file)
--- a/docs/user/advanced.rst
+++ b/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
 ------------------

diff --git a/requests/adapters.py b/requests/adapters.py
index b62f64c..ba468e8 100644 (file)
--- a/requests/adapters.py
+++ b/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',

diff --git a/requests/models.py b/requests/models.py
index 061c93b..ae46a83 100644 (file)
--- a/requests/models.py
+++ b/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
 

diff --git a/requests/sessions.py b/requests/sessions.py
index 2aae6e4..db227ca 100644 (file)
--- a/requests/sessions.py
+++ b/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 {}