Document the environment variables that can affect the behavior of PyGMT (#3432)

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

Author: seisman

doc/_static/style.css

@@ -219,3 +219,7 @@ th.text-center, td.text-center {
 th.text-right, td.text-right {
     text-align: right !important;
 }
+
+.std-term {
+	font-weight: 600;
+}

doc/install.md

@@ -269,17 +269,17 @@ problems and solutions.
 Sometimes, PyGMT will be unable to find the correct version of the GMT shared library
 (`libgmt`). This can happen if you have multiple versions of GMT installed.
 
-You can tell PyGMT exactly where to look for `libgmt` by setting the `GMT_LIBRARY_PATH`
-environment variable to the directory where `libgmt.so`, `libgmt.dylib` or `gmt.dll` can
-be found on Linux, macOS or Windows, respectively.
+You can tell PyGMT exactly where to look for `libgmt` by setting the environment
+variable {term}`GMT_LIBRARY_PATH` to the directory where `libgmt.so`, `libgmt.dylib` or
+`gmt.dll` can be found on Linux, macOS or Windows, respectively.
 
 For Linux/macOS, add the following line to your shell configuration file (usually
 `~/.bashrc` for Bash on Linux and `~/.zshrc` for Zsh on macOS):
 ```
 export GMT_LIBRARY_PATH=$HOME/miniforge3/envs/pygmt/lib
 ```
 
-For Windows, add the `GMT_LIBRARY_PATH` environment variable following these
+For Windows, add the environment variable {term}`GMT_LIBRARY_PATH` following these
 [instructions](https://www.wikihow.com/Create-an-Environment-Variable-in-Windows-10)
 and set its value to a path like:
 ```

doc/techref/environment_variables.md

@@ -0,0 +1,46 @@
+# Environment Variables
+
+PyGMT's behavior can be controlled through various environment variables. These variables
+can be set either in your shell environment or within your Python script using the
+{py:data}`os.environ` dictionary.
+
+Here we list the environment variables used by PyGMT which are categorized into three groups:
+
+1. System environment variables
+2. GMT/PyGMT environment variables
+3. Module-specific environment variables
+
+## System Environment Variables
+
+```{glossary}
+TZ
+    Specify the time zone for the current calendar time. It can be set to a string that
+    defines the timezone, such as `"UTC"`, `"America/New_York"`, or `"Europe/London"`.
+    Refer to [Specifying the Time Zone with TZ](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html)
+    for the valid format. If not set, the system's default timezone is used.
+```
+
+## GMT/PyGMT Environment Variables
+
+```{glossary}
+GMT_LIBRARY_PATH
+    Specify the directory where the GMT shared library is located. This is useful when
+    GMT is installed in a non-standard location or when you want to use a specific
+    version of GMT. If not set, PyGMT will attempt to find the GMT library in standard
+    system locations.
+
+PYGMT_USE_EXTERNAL_DISPLAY
+    Whether to use external viewers for displaying images. If set to `"false"`, PyGMT
+    will not attempt to open images in external viewers. This can be useful when running
+    tests or building the documentation to avoid popping up windows.
+```
+
+## Module-Specific Environment Variables
+
+```{glossary}
+X2SYS_HOME
+    Specify the directory where x2sys databases and related settings will be stored.
+    This environment variable is used by x2sys-related functions (e.g.,
+    {func}`pygmt.x2sys_init`) to manage and access x2sys data. If not set, these
+    functions will use a default directory or prompt for a location.
+```

doc/techref/index.md

@@ -11,4 +11,5 @@ visit the {gmt-docs}`GMT Technical Reference <reference.html>`.
 projections.md
 fonts.md
 encodings.md
+environment_variables
 ```

pygmt/clib/loading.py

@@ -2,7 +2,7 @@
 Utility functions to load libgmt as ctypes.CDLL.
 
 The path to the shared library can be found automatically by ctypes or set through the
-GMT_LIBRARY_PATH environment variable.
+environment variable :term:`GMT_LIBRARY_PATH`.
 """
 
 import ctypes
@@ -128,9 +128,9 @@ def clib_full_names(env: Mapping | None = None) -> Iterator[str]:
 
     The GMT shared library is searched for in following ways, sorted by priority:
 
-    1. Path defined by environmental variable GMT_LIBRARY_PATH
-    2. Path returned by command "gmt --show-library"
-    3. Path defined by environmental variable PATH (Windows only)
+    1. Path defined by the environment variable :term:`GMT_LIBRARY_PATH`
+    2. Path returned by the command "gmt --show-library"
+    3. Path defined by the environment variable PATH (Windows only)
     4. System default search path
 
     Parameters

pygmt/clib/session.py

@@ -116,7 +116,7 @@ class Session:
     same ``with`` block as the API calls that will use the data.
 
     By default, will let :mod:`ctypes` try to find the GMT shared library
-    (``libgmt``). If the environment variable ``GMT_LIBRARY_PATH`` is set, will
+    (``libgmt``). If the environment variable :term:`GMT_LIBRARY_PATH` is set, will
     look for the shared library in the directory specified by it.
 
     A ``GMTVersionError`` exception will be raised if the GMT shared library

pygmt/figure.py

@@ -43,7 +43,7 @@ def _get_default_display_method() -> Literal["external", "notebook", "none"]:
     The default display method is ``"notebook"`` in the Jupyter notebook environment,
     and ``"external"`` in other cases.
 
-    Setting environment variable **PYGMT_USE_EXTERNAL_DISPLAY** to ``"false"`` can
+    Setting environment variable :term:`PYGMT_USE_EXTERNAL_DISPLAY` to ``"false"`` can
     disable image preview in external viewers. It's useful when running the tests and
     building the documentation to avoid popping up windows.
 
@@ -421,8 +421,8 @@ def show(
         resolution and dimension of the figure in the notebook.
 
         The external viewer can be disabled by setting the environment variable
-        **PYGMT_USE_EXTERNAL_DISPLAY** to ``"false"``. This is useful when running tests
-        and building the documentation to avoid popping up windows.
+        :term:`PYGMT_USE_EXTERNAL_DISPLAY` to ``"false"``. This is useful when running
+        tests and building the documentation to avoid popping up windows.
 
         The external viewer does not block the current process, thus it's necessary to
         suspend the execution of the current process for a short while after launching

pygmt/src/timestamp.py

@@ -27,7 +27,7 @@ def timestamp(
 
     Add the GMT timestamp logo with an optional label at the bottom-left corner of a
     plot with an offset of ``("-54p", "-54p")``. The timestamp will be in the locale set
-    by the environment variable **TZ** (generally local time but can be changed via
+    by the environment variable :term:`TZ` (generally local time but can be changed via
     ``os.environ["TZ"]``) and its format is controlled by the ``timefmt`` parameter. It
     can also be replaced with any custom text string using the ``text`` parameter.
 

pygmt/src/x2sys_cross.py

@@ -96,13 +96,13 @@ def x2sys_cross(
         or file names. Supported file formats are ASCII, native binary, or
         COARDS netCDF 1-D data. More columns may also be present.
 
-        If the file names are missing their file extension, we will append the
-        suffix specified for this TAG. Track files will be searched for first
-        in the current directory and second in all directories listed in
-        $X2SYS_HOME/TAG/TAG_paths.txt (if it exists). [If $X2SYS_HOME is not
-        set it will default to $GMT_SHAREDIR/x2sys]. (**Note**: MGD77 files
-        will also be looked for via $MGD77_HOME/mgd77_paths.txt and .gmt
-        files will be searched for via $GMT_SHAREDIR/mgg/gmtfile_paths).
+        If the file names are missing their file extension, we will append the suffix
+        specified for this TAG. Track files will be searched for first in the current
+        directory and second in all directories listed in $X2SYS_HOME/TAG/TAG_paths.txt
+        (if it exists). [If environment variable :term:`X2SYS_HOME` is not set it will
+        default to $GMT_SHAREDIR/x2sys]. (**Note**: MGD77 files will also be looked for
+        via $MGD77_HOME/mgd77_paths.txt and .gmt files will be searched for via
+        $GMT_SHAREDIR/mgg/gmtfile_paths).
 
     outfile
         The file name for the output ASCII txt file to store the table in.

pygmt/src/x2sys_init.py

@@ -30,9 +30,9 @@ def x2sys_init(tag, **kwargs):
     x2sys TAG. The TAG keeps track of settings such as file format, whether the
     data are geographic or not, and the binning resolution for track indices.
 
-    Before you can run :func:`pygmt.x2sys_init` you must set the environmental
-    parameter X2SYS_HOME to a directory where you have write permission, which
-    is where x2sys can keep track of your settings.
+    Before you can run :func:`pygmt.x2sys_init` you must set the environment variable
+    :term:`X2SYS_HOME` to a directory where you have write permission, which is where
+    x2sys can keep track of your settings.
 
     Full option list at :gmt-docs:`supplements/x2sys/x2sys_init.html`