DOC: Add gallery example for using EPSG codes

doc/conf.py

@@ -182,7 +182,7 @@
         "../examples/projections/cyl",
         "../examples/projections/misc",
         "../examples/projections/nongeo",
-        "../examples/projections/table",
+        "../examples/projections/epsg",
     ],
     # Pattern to search for example files
     "filename_pattern": r"\.py",

doc/techref/projections.md

@@ -12,7 +12,8 @@ myst:
 
 # GMT Map Projections
 
-The table below shows the projection codes for the 31 GMT map projections:
+The table below shows the projection codes for the 31 GMT map projections. Besides these
+GMT-specific projection codes, [EPSG codes](/projections/epsg) are supported.
 
 | PyGMT Projection Argument | Projection Name |
 | --- | --- |

examples/projections/GALLERY_HEADER.rst

@@ -6,6 +6,7 @@ Use the ``projection`` parameter to specify which one you want to use in all plo
 methods. The projection is specified by a one-letter code along with (sometimes optional)
 reference longitude and latitude and the width of the map (for example,
 **A**\ *lon0/lat0*\ [*/horizon*\ ]\ */width*). The map height is determined based on the
-region and projection.
+region and projection. Beside these GMT-specific projection codes,
+:doc:`EPSG codes </projections/epsg>` are supported.
 
 These are all the available projections:

examples/projections/epsg/GALLERY_HEADER.rst

@@ -0,0 +1,2 @@
+EPSG codes
+----------

examples/projections/epsg/epsg_codes.py

@@ -0,0 +1,23 @@
+"""
+EPSG codes
+==========
+
+Besides one of the :doc:`31 projections supported by GMT </techref/projections>`, users
+can pass an EPSG (European Petroleum Survey Group) code to the ``projection`` parameter
+of the methods :meth:`Figure.basemap` and :meth:`Figure.coast`. A commonly used EPSG
+code is ``EPSG:3857``, that refers to the Web Mercator projection WGS84. More
+information on the EPSG dataset can be found at https://epsg.org and
+https://spatialreference.org/.
+"""
+
+# %%
+import pygmt
+
+fig = pygmt.Figure()
+
+# Pass the desired EPSG code and the width of the map, here 10 centimeters, to the
+# projection parameter
+fig.basemap(region=[-180, 180, -60, 60], projection="EPSG:3857/10c", frame=30)
+fig.coast(land="gray", shorelines="1/0.1p,gray10")
+
+fig.show()