Add with warnings.catch_warnings() example to API docs (#670)

The new section explains how to suppress warning for only parts as opposed to
for the entire program. The former is the preferred method.

Author: robsdedude

docs/source/api.rst

@@ -1405,13 +1405,35 @@ Filter Warnings
 
 This example shows how to suppress the :class:`neo4j.ExperimentalWarning` using the :func:`python:warnings.filterwarnings` function.
 
+.. code-block:: python
+
+    import warnings
+    from neo4j import ExperimentalWarning
+
+    ...
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=ExperimentalWarning)
+        ...  # the call emitting the ExperimentalWarning
+
+    ...
+
+This will only mute the :class:`neo4j.ExperimentalWarning` for everything inside
+the ``with``-block. This is the preferred way to mute warnings, as warnings
+triggerd by new code will still be visible.
+
+However, should you want to mute it for the entire application, use the
+following code:
+
 .. code-block:: python
 
     import warnings
     from neo4j import ExperimentalWarning
 
     warnings.filterwarnings("ignore", category=ExperimentalWarning)
 
+    ...
+
 
 *********
 Bookmarks

docs/source/async_api.rst

@@ -10,6 +10,8 @@ Async API Documentation
     This means everything documented on this page might be removed or change
     its API at any time (including in patch releases).
 
+    (See :ref:`filter-warnings-ref`)
+
 .. versionadded:: 5.0
 
 ******************