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

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

@@ -1346,13 +1346,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)
 
+    ...
+
 
 ********
 Bookmark