From 1e719874157546712b483d2cc5af840b5cbbb65c Mon Sep 17 00:00:00 2001
From: Christoph Deil <Deil.Christoph@gmail.com>
Date: Thu, 28 May 2015 09:27:11 +0200
Subject: [PATCH] Improve docs page on Python warnings system

---
 docs/warnings.rst | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/warnings.rst b/docs/warnings.rst
index 7b24542f551..1e16df015c0 100644
--- a/docs/warnings.rst
+++ b/docs/warnings.rst
@@ -22,27 +22,32 @@ follows::
 It is also possible to suppress warnings from within a python script.  For
 instance, the warnings issued from a single call to the
 `astropy.io.fits.writeto` function may be suppressed from within a Python
-script as follows::
+script using the `warnings.filterwarnings` function as follows::
 
      >>> import warnings
      >>> from astropy.io import fits
      >>> warnings.filterwarnings('ignore', category=UserWarning, append=True)
      >>> fits.writeto(filename, data, clobber=True)
 
+An equivalent way to insert an entry into the list of warning filter specifications
+for simple call `warnings.simplefilter`::
+
+    >>> warnings.simplefilter('ignore', UserWarning)
+
 Astropy includes its own warning class,
 `~astropy.utils.exceptions.AstropyUserWarning`, on which all warnings from
 Astropy are based.  So one can also ignore warnings from Astropy (while still
 allowing through warnings from other libraries like Numpy) by using something
 like::
 
-    >>> warnings.filterwarnings('ignore', category=AstropyUserWarning)
+    >>> from astropy.utils.exceptions import AstropyUserWarning
+    >>> warnings.simplefilter('ignore', category=AstropyUserWarning)
 
 However, warning filters may also be modified just within a certain context
-using the `~warnings.catch_warnings` context manager::
+using the `warnings.catch_warnings` context manager::
 
-    >>> from warnings import catch_warnings
-    >>> with catch_warnings():
-    ...     warnings.filterwarnings('ignore', category=AstropyUserWarning)
+    >>> with warnings.catch_warnings():
+    ...     warnings.simplefilter('ignore', AstropyUserWarning)
     ...     fits.writeto(filename, data, clobber=True)
 
 Astropy also issues warnings when deprecated API features are used.  If you