Add show_versions() function for printing information useful when sub…

…mitting bug reports (#466)

The `show_versions` function reports

- PyGMT version
- system information
- dependency version
- GMT library information

The GitHub issue template and the install instruction are also updated.

Co-authored-by: Wei Ji <[email protected]>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -22,16 +22,8 @@ PASTE ERROR MESSAGE HERE
 
 **System information**
 
-* Operating system:
-* Python installation (Anaconda, system, ETS):
-* Version of GMT:
-* Version of Python:
-* Version of this package:
-* If using conda, paste the output of `conda list` below:
-
-<details>
-<summary>output of conda list</summary>
-<pre>
-PASTE OUTPUT OF CONDA LIST HERE
-</pre>
-</details>
+Please paste the output of `python -c "import pygmt; pygmt.show_versions()"`:
+
+```
+PASTE THE OUTPUT HERE
+```

Makefile

@@ -24,7 +24,7 @@ test:
 	# Run a tmp folder to make sure the tests are run on the installed version
 	mkdir -p $(TESTDIR)
 	@echo ""
-	@cd $(TESTDIR); python -c "import $(PROJECT); $(PROJECT).print_clib_info()"
+	@cd $(TESTDIR); python -c "import $(PROJECT); $(PROJECT).show_versions()"
 	@echo ""
 	cd $(TESTDIR); pytest $(PYTEST_ARGS) $(PROJECT)
 	cp $(TESTDIR)/.coverage* .

doc/api/index.rst

@@ -92,6 +92,7 @@ Miscellaneous
     which
     test
     print_clib_info
+    show_versions
 
 
 .. automodule:: pygmt.datasets

doc/install.rst

@@ -117,7 +117,7 @@ well (be sure to have your conda env activated)::
 Test your installation by running the following inside a Python interpreter::
 
     import pygmt
-    pygmt.print_clib_info()
+    pygmt.show_versions()
     pygmt.test()
 
 

pygmt/__init__.py

@@ -41,13 +41,98 @@ def print_clib_info():
     """
     from .clib import Session
 
-    lines = ["Loaded libgmt:"]
+    lines = ["GMT library information:"]
     with Session() as ses:
         for key in sorted(ses.info):
             lines.append("  {}: {}".format(key, ses.info[key]))
     print("\n".join(lines))
 
 
+def show_versions():
+    """
+    Prints various dependency versions useful when submitting bug reports. This
+    includes information about:
+
+    - PyGMT itself
+    - System information (Python version, Operating System)
+    - Core dependency versions (Numpy, Pandas, Xarray, etc)
+    - GMT library information
+    """
+
+    import sys
+    import platform
+    import importlib
+    import subprocess
+
+    def _get_module_version(modname):
+        """Get version information of a Python module."""
+        try:
+            if modname in sys.modules:
+                module = sys.modules[modname]
+            else:
+                module = importlib.import_module(modname)
+
+            try:
+                return module.__version__
+            except AttributeError:
+                return module.version
+        except ImportError:
+            return None
+
+    def _get_ghostscript_version():
+        """Get ghostscript version."""
+        os_name = sys.platform
+        if os_name.startswith("linux") or os_name == "darwin":
+            cmds = ["gs"]
+        elif os_name == "win32":
+            cmds = ["gswin64c.exe", "gswin32c.exe"]
+        else:
+            return None
+
+        for gs_cmd in cmds:
+            try:
+                version = subprocess.check_output(
+                    [gs_cmd, "--version"], universal_newlines=True
+                ).strip()
+                return version
+            except FileNotFoundError:
+                continue
+        return None
+
+    def _get_gmt_version():
+        """Get GMT version."""
+        try:
+            version = subprocess.check_output(
+                ["gmt", "--version"], universal_newlines=True
+            ).strip()
+            return version
+        except FileNotFoundError:
+            return None
+
+    sys_info = {
+        "python": sys.version.replace("\n", " "),
+        "executable": sys.executable,
+        "machine": platform.platform(),
+    }
+
+    deps = ["numpy", "pandas", "xarray", "netCDF4", "packaging"]
+
+    print("PyGMT information:")
+    print(f"  version: {__version__}")
+
+    print("System information:")
+    for k, v in sys_info.items():
+        print(f"  {k}: {v}")
+
+    print("Dependency information:")
+    for modname in deps:
+        print(f"  {modname}: {_get_module_version(modname)}")
+    print(f"  ghostscript: {_get_ghostscript_version()}")
+    print(f"  gmt: {_get_gmt_version()}")
+
+    print_clib_info()
+
+
 def test(doctest=True, verbose=True, coverage=False, figures=True):
     """
     Run the test suite.
@@ -81,7 +166,7 @@ def test(doctest=True, verbose=True, coverage=False, figures=True):
     """
     import pytest
 
-    print_clib_info()
+    show_versions()
 
     package = __name__