pygmt.set_display: Add inline examples and improve documentation (#2458)

Co-authored-by: Yvonne Fröhlich <[email protected]>

pygmt/figure.py

@@ -339,7 +339,7 @@ def show(self, dpi=300, width=500, method=None, waiting=0.5, **kwargs):
  (falls back to the default web browser).
 
  :func:`pygmt.set_display` can select the default display method
- (**notebook**, **external**, or **none**).
+ (``"notebook"``, ``"external"``, ``"none"`` or ``None``).
 
  The ``method`` parameter can also override the default display method
  for the current figure. Parameters ``dpi`` and ``width`` can be used
@@ -362,12 +362,17 @@ def show(self, dpi=300, width=500, method=None, waiting=0.5, **kwargs):
  The image resolution (dots per inch) in Jupyter notebooks.
  width : int
  The image width (in pixels) in Jupyter notebooks.
- method : str
- How the current figure will be displayed. Options are
+ method : str or None
+ How the current figure will be displayed. Choose from:
 
- - **external**: PDF preview in an external program [Default]
- - **notebook**: PNG preview [Default in Jupyter notebooks]
- - **none**: Disable image preview
+ - ``"external"``: External PDF preview using the default PDF viewer
+ - ``"notebook"``: Inline PNG preview in the current notebook
+ - ``"none"``: Disable image preview
+ - ``None``: Reset to the default display method
+
+ The default display method is ``"external"`` in Python consoles or
+ ``"notebook"`` in Jupyter notebooks, but can be changed by
+ :func:`pygmt.set_display`.
  waiting : float
  Suspend the execution of the current process for a given number of
  seconds after launching an external viewer.
@@ -526,23 +531,48 @@ def _repr_html_(self):
 
 def set_display(method=None):
  """
- Set the display method.
+ Set the display method when calling :meth:`pygmt.Figure.show`.
 
  Parameters
  ----------
  method : str or None
- The method to display an image. Choose from:
+ The method to display an image preview. Choose from:
+
+ - ``"external"``: External PDF preview using the default PDF viewer
+ - ``"notebook"``: Inline PNG preview in the current notebook
+ - ``"none"``: Disable image preview
+ - ``None``: Reset to the default display method
+
+ The default display method is ``"external"`` in Python consoles or
+ ``"notebook"`` in Jupyter notebooks.
+
+ Examples
+ --------
+ Let's assume that you're using a Jupyter Notebook:
 
- - **external**: PDF preview in an external program [Default]
- - **notebook**: PNG preview [Default in Jupyter notebooks]
- - **none**: Disable image preview
+ >>> import pygmt
+ >>> fig = pygmt.Figure()
+ >>> fig.basemap(region=[0, 10, 0, 10], projection="X10c/5c", frame=True)
+ >>> fig.show() # will display a PNG image in the current notebook
+ >>>
+ >>> # set the display method to "external"
+ >>> pygmt.set_display(method="external") # doctest: +SKIP
+ >>> fig.show() # will display a PDF image using the default PDF viewer
+ >>>
+ >>> # set the display method to "none"
+ >>> pygmt.set_display(method="none")
+ >>> fig.show() # will not show any image
+ >>>
+ >>> # reset to the default display method
+ >>> pygmt.set_display(method=None)
+ >>> fig.show() # again, will show a PNG image in the current notebook
  """
  if method in ["notebook", "external", "none"]:
  SHOW_CONFIG["method"] = method
  elif method is not None:
  raise GMTInvalidInput(
  (
  f"Invalid display mode '{method}', "
- "should be either 'notebook', 'external' or 'none'."
+ "should be either 'notebook', 'external', 'none' or None."
  )
  )