Add deprecation warning handling advice note (#5346)

* Add deprecation warning handling advice note

This tip is being added to help the library maintainers keep
testing cryptography where supporting multiple Python runtime
is still necessary.

Resolves https://github.com/pyca/cryptography/issues/5335

* Move deprecation suppression advice to FAQ

CHANGELOG.rst

@@ -37,6 +37,10 @@ Changelog
   actually dropping support, however we strongly encourage all users to upgrade
   their Python, as Python 2 no longer receives support from the Python core
   team.
+
+  If you have trouble suppressing this warning, please, check out :ref:`an FAQ
+  entry about addressing this issue <faq-howto-handle-deprecation-warning>`.
+
 * Added support for ``OpenSSH`` serialization format for
   ``ec``, ``ed25519``, ``rsa`` and ``dsa`` private keys:
   :func:`~cryptography.hazmat.primitives.serialization.load_ssh_private_key`

docs/faq.rst

@@ -1,6 +1,33 @@
 Frequently asked questions
 ==========================
 
+.. _faq-howto-handle-deprecation-warning:
+
+I cannot suppress the deprecation warning that ``cryptography`` emits on import
+-------------------------------------------------------------------------------
+
+.. hint::
+
+   The deprecation warning emitted on import does not inherit
+   :py:exc:`DeprecationWarning` but inherits :py:exc:`UserWarning`
+   instead.
+
+If your pytest setup follows the best practices of failing on
+emitted warnings (``filterwarnings = error``), you may ignore it
+by adding the following line at the end of the list::
+
+   ignore:Python 2 is no longer supported by the Python core team. Support for it is now deprecated in cryptography, and will be removed in a future release.:UserWarning:cryptography
+
+**Note:** Using ``cryptography.utils.CryptographyDeprecationWarning``
+is not possible here because specifying it triggers
+``import cryptography`` internally that emits the warning before
+the ignore rule even kicks in.
+
+Ref: https://github.com/pytest-dev/pytest/issues/7524
+
+The same applies when you use :py:func:`~warnings.filterwarnings` in
+your code or invoke CPython with :std:option:`-W` command line option.
+
 ``cryptography`` failed to install!
 -----------------------------------
 

docs/spelling_wordlist.txt

@@ -19,6 +19,7 @@ codebook
 committer
 committers
 conda
+CPython
 Cryptanalysis
 crypto
 cryptographic
@@ -88,6 +89,7 @@ preprocessors
 presentational
 pseudorandom
 pyOpenSSL
+pytest
 relicensed
 responder
 runtime