Repository: urllib3/urllib3

Issue:
Update all code examples to new guidance for consistency
- [x] Switch all `.. code-block: pycon` to `.. code-block: python`
- [x] Remove `>>> ` and `... ` in favor of whitespace to create readable code examples that can be copy-pasted and run immediately.
  - This includes making sure imports are done properly in every block.
- [x] Use the top-level `urllib3.request()` function for smaller code examples. For more involved examples use `PoolManager`, etc
- [x] Use keyword arguments everywhere except for `method` and `url` (ie `http.request("GET", "https://example.com", headers={...})`)
- [x] Use HTTPS in URLs everywhere unless HTTP is needed
- [x] Rules for naming variables:
  - `PoolManager` should be `http`
  - `ProxyManager` should be `proxy`
  - `ConnectionPool` should be `pool`
  - `Connection` should be `conn`
  - `HTTPResponse` should be `resp` (ie `resp = http.request("GET", "https://example.com")`)
  - Only use `example.com` or `httpbin.org` for example URLs
- [x] Switch from `:ret: ...` to `:returns: ...` for better readability of API documentation ("RET" vs "RETURNS")
- [x] Comments within snippets should be useful, if what's being done is apparent (such as parsing JSON, making a request) then it can be skipped for that section. Comments should always go above a code section rather than below with the exception of `print` statements where the comment containing the result goes below.
- [ ] Imports should be their own section separated from the rest of the example with a line of whitespace. Imports should minimized if possible. Use `import urllib3` instead of `from urllib3 import X`. Sort imports similarly to `isort`, standard library first and third-party (like urllib3) come after. No whitespace is required between the sections as normally would be in case of `isort`.
- [ ] Add `print` statements along with a comment below them showing the output, potentially compressed.
      This helps users using the copy-paste button immediately see the results from a script.
- [x] Update the contribution guidelines to include this guidance
- [x] Maybe we can also start using [`sphinx-copybutton`](https://github.com/executablebooks/sphinx-copybutton) as a part of this issue too?

If anyone has thoughts on any of these individual items or has other ideas let me know!


Discussion:
We should make it amply clear that using `urllib3.request(...)` _will_ reuse connections behind the scenes, that it's using a module-global default PoolManager. (It says this in the docstring for the function but would be good to mention it in the first example using it.)
A _copy button_ would be a great improvement. Right now copying lines from the code examples is painful.
Added guidance on code comments, imports, and displaying results to users via `print`.

Resolving patch:
diff --git a/src/urllib3/fields.py b/src/urllib3/fields.py
--- a/src/urllib3/fields.py
+++ b/src/urllib3/fields.py
@@ -47,7 +47,7 @@ def format_header_param_rfc2231(name: str, value: Union[str, bytes]) -> str:
         The name of the parameter, a string expected to be ASCII only.
     :param value:
         The value of the parameter, provided as ``bytes`` or `str``.
-    :ret:
+    :returns:
         An RFC-2231-formatted unicode string.
     """
     if isinstance(value, bytes):
@@ -109,7 +109,7 @@ def format_header_param_html5(name: str, value: _TYPE_FIELD_VALUE) -> str:
         The name of the parameter, a string expected to be ASCII only.
     :param value:
         The value of the parameter, provided as ``bytes`` or `str``.
-    :ret:
+    :returns:
         A unicode string, stripped of troublesome characters.
     """
     if isinstance(value, bytes):


Test patch: