diff --git a/doc/_static/style.css b/doc/_static/style.css index 2681160e4b8..7ab009e31ec 100644 --- a/doc/_static/style.css +++ b/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; +} diff --git a/doc/install.md b/doc/install.md index 12cec95a62d..e94b68ee914 100644 --- a/doc/install.md +++ b/doc/install.md @@ -269,9 +269,9 @@ 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): @@ -279,7 +279,7 @@ For Linux/macOS, add the following line to your shell configuration file (usuall 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: ``` diff --git a/doc/techref/environment_variables.md b/doc/techref/environment_variables.md new file mode 100644 index 00000000000..cc0ab0605a7 --- /dev/null +++ b/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. +``` diff --git a/doc/techref/index.md b/doc/techref/index.md index dd4c9782a3c..93dee91fe85 100644 --- a/doc/techref/index.md +++ b/doc/techref/index.md @@ -11,4 +11,5 @@ visit the {gmt-docs}`GMT Technical Reference `. projections.md fonts.md encodings.md +environment_variables ``` diff --git a/pygmt/clib/loading.py b/pygmt/clib/loading.py index 60541c7186d..7034bf103df 100644 --- a/pygmt/clib/loading.py +++ b/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 diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index cdfc3bc4963..95ed8c19d76 100644 --- a/pygmt/clib/session.py +++ b/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 diff --git a/pygmt/figure.py b/pygmt/figure.py index 91a4193f6f0..09777bd4eb1 100644 --- a/pygmt/figure.py +++ b/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 diff --git a/pygmt/src/timestamp.py b/pygmt/src/timestamp.py index 2b3e1f6f51b..39a6c25bf39 100644 --- a/pygmt/src/timestamp.py +++ b/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. diff --git a/pygmt/src/x2sys_cross.py b/pygmt/src/x2sys_cross.py index af79cfee852..79daf523fec 100644 --- a/pygmt/src/x2sys_cross.py +++ b/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. diff --git a/pygmt/src/x2sys_init.py b/pygmt/src/x2sys_init.py index b6ce159abc7..99af7211424 100644 --- a/pygmt/src/x2sys_init.py +++ b/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`