Docs: clarify the precedence of auth= over netrc

This closes #2062 by clarifying in the docs which auth
header takes precedence:
1st auth=
2nd .netrc
3rd headers=

This precedence order is already tested in test_requests.py,
in the test_basicauth_with_netrc method. Perhaps we should
add further tests for non-basic auth schemes.

docs/user/authentication.rst

@@ -37,7 +37,8 @@ netrc Authentication
 
 If no authentication method is given with the ``auth`` argument, Requests will
 attempt to get the authentication credentials for the URL's hostname from the
-user's netrc file.
+user's netrc file. The netrc file overrides raw HTTP authentication headers
+set with `headers=`.
 
 If credentials for the hostname are found, the request is sent with HTTP Basic
 Auth.
@@ -125,4 +126,3 @@ Further examples can be found under the `Requests organization`_ and in the
 .. _Kerberos: https://github.com/requests/requests-kerberos
 .. _NTLM: https://github.com/requests/requests-ntlm
 .. _Requests organization: https://github.com/requests
-

docs/user/quickstart.rst

@@ -197,7 +197,9 @@ For example, we didn't specify our user-agent in the previous example::
 
 Note: Custom headers are given less precedence than more specific sources of information. For instance:
 
-* Authorization headers will be overridden if credentials are passed via the ``auth`` parameter or are specified in a ``.netrc`` accessible in the environment.
+* Authorization headers set with `headers=` will be overridden if credentials
+are specified in ``.netrc``, which in turn will be overridden by the  ``auth=``
+parameter.
 * Authorization headers will be removed if you get redirected off-host.
 * Proxy-Authorization headers will be overridden by proxy credentials provided in the URL.
 * Content-Length headers will be overridden when we can determine the length of the content.