GMT-Ghostscript incompatibility: Give recommendations and extend examples (#3249)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Michael Grund <[email protected]>

Author: 3 people

.github/ISSUE_TEMPLATE/4-release_checklist.md

@@ -23,6 +23,8 @@ assignees: ''
   - [ ] All tests pass in the ["GMT Dev Tests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_tests_dev.yaml)
   - [ ] All tests pass in the ["Doctests" workflow](https://github.com/GenericMappingTools/pygmt/actions/workflows/ci_doctests.yaml)
   - [ ] Deprecations and related tests are removed for this version by running `grep --include="*.py" -r 'remove_version="vX.Y.Z"' pygmt` from the base of the repository
+- [ ] Update warnings in `pygmt.show_versions()` as well as notes in [Common installation issues](https://www.pygmt.org/dev/install.html#not-working-transparency)
+      and [Testing your install]((https://www.pygmt.org/dev/install.html#testing-your-install) regarding GMT-Ghostscript incompatibility
 - [ ] Reserve a DOI on [Zenodo](https://zenodo.org) by clicking on "New Version"
 - [ ] Review the ["PyGMT Team" page](https://www.pygmt.org/dev/team.html)
 - [ ] Finish up 'Changelog entry for v0.x.x' Pull Request:

README.md

@@ -74,11 +74,14 @@ or a [Jupyter notebook](https://docs.jupyter.org/en/latest/running.html), and tr
 ``` python
 import pygmt
 fig = pygmt.Figure()
-fig.coast(projection="H10c", region="g", frame=True, land="gray")
+fig.coast(projection="N15c", region="g", frame=True, land="tan", water="lightblue")
+fig.text(position="MC", text="PyGMT", font="80p,Helvetica-Bold,red@75")
 fig.show()
 ```
 
-For more examples, please have a look at the [Gallery](https://www.pygmt.org/latest/gallery/index.html) and
+You should see a global map with land and water masses colored in tan and lightblue, respectively. On top,
+there should be the semi-transparent text "PyGMT". For more examples, please have a look at the
+[Gallery](https://www.pygmt.org/latest/gallery/index.html) and
 [Tutorials](https://www.pygmt.org/latest/tutorials/index.html).
 
 ## Contacting us

doc/install.md

@@ -105,7 +105,7 @@ If you have [PyArrow](https://arrow.apache.org/docs/python/index.html) installed
 does have some initial support for `pandas.Series` and `pandas.DataFrame` objects with
 Apache Arrow-backed arrays. Specifically, only uint/int/float and date32/date64 dtypes
 are supported for now. Support for string Arrow dtypes is still a work in progress.
-For  more details, see [issue #2800](https://github.com/GenericMappingTools/pygmt/issues/2800).
+For more details, see [issue #2800](https://github.com/GenericMappingTools/pygmt/issues/2800).
 :::
 
 ## Installing GMT and other dependencies
@@ -238,11 +238,17 @@ import pygmt
 pygmt.show_versions()
 
 fig = pygmt.Figure()
-fig.coast(region="g", frame=True, shorelines=1)
+fig.coast(projection="N15c", region="g", frame=True, land="tan", water="lightblue")
+fig.text(position="MC", text="PyGMT", font="80p,Helvetica-Bold,red@75")
 fig.show()
 ```
+![pygmt-get-started](https://github.com/GenericMappingTools/pygmt/assets/3974108/f7f51484-8640-4b58-ae5b-6c71e7150f7a){.align-center width="70%"}
 
-If you see a global map with shorelines, then you're all set.
+You should see a global map with land and water masses colored in tan and lightblue
+respectively. On top, there should be the semi-transparent text "PyGMT". If the
+semi-transparency does not show up, there is probably an incompatibility between your
+GMT and Ghostscript versions. For details, please run `pygmt.show_versions()` and see
+[Not working transparency](#not-working-transparency).
 
 ## Common installation issues
 
@@ -284,3 +290,14 @@ jupyter kernelspec list --json
 
 After that, you need to restart Jupyter, open your notebook, select the `pygmt` kernel
 and then import pygmt.
+
+
+### Not working transparency
+
+It is known that some combinations of GMT and Ghostscript versions cause issues,
+especially regarding transparency. If the transparency doesn't work in your figures,
+please check your GMT and Ghostscript versions (you can run `pygmt.show_versions()`).
+We recommend:
+
+- Ghostscript 9.53-9.56 for GMT 6.3.0/6.4.0
+- Ghostscript 10.03 or later for GMT 6.5.0