From 7a48416cb3b1e1edfe0152e6bf5e8d570e704166 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 9 Sep 2024 23:46:49 +0800 Subject: [PATCH 1/8] Add a page for environment variables used in PyGMT --- doc/techref/environment_variables.md | 35 ++++++++++++++++++++++++++++ doc/techref/index.md | 1 + 2 files changed, 36 insertions(+) create mode 100644 doc/techref/environment_variables.md diff --git a/doc/techref/environment_variables.md b/doc/techref/environment_variables.md new file mode 100644 index 00000000000..bf93c028e05 --- /dev/null +++ b/doc/techref/environment_variables.md @@ -0,0 +1,35 @@ +# Environmental Variables + +Several environment variables can be used to control the behavior of PyGMT. These +environment variables can be set in your shell or in your Python script using the +`os.environ` dictionary. + +Here we list the environment variables that are used by PyGMT. The environment +variables are divided into three categories: system environment variables, GMT/PyGMT +environment variables, and module-specific environment variables. + +## System Environment Variables + +```{glossary} +TZ + Specify the time zone for the current calendar time. Refer to the + [Specifying the Time Zone with TZ](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html) + for the valid format. +``` + +## GMT/PyGMT Environment Variables + +```{glossary} +PYGMT_USE_EXTERNAL_DISPLAY + Setting this environment variable 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. +``` + +## Module-Specific Environment Variables + +```{glossary} +X2SYS_HOME + Specify the directory where the x2sys-related functions (e.g., + {func}`pygmt.x2sys_init`) can keep track of the x2sys settings. +``` 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 ``` From 362c1dd65548765edcb139c8858703ae062c56c7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 9 Sep 2024 23:47:34 +0800 Subject: [PATCH 2/8] Link to these environment variable using the term role --- pygmt/figure.py | 6 +++--- pygmt/src/timestamp.py | 2 +- pygmt/src/x2sys_cross.py | 14 +++++++------- pygmt/src/x2sys_init.py | 6 +++--- 4 files changed, 14 insertions(+), 14 deletions(-) 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..fae77a39af6 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 environmental 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` From 5616d876631ce984b0f5c9bec12e97d4c054f600 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Mon, 9 Sep 2024 23:48:19 +0800 Subject: [PATCH 3/8] Set the font-weight for std-term class --- doc/_static/style.css | 4 ++++ 1 file changed, 4 insertions(+) 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; +} From 4eac3b1788e34e3eb88b25820508b509d6597590 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Tue, 10 Sep 2024 15:21:34 +0800 Subject: [PATCH 4/8] Add GMT_LIBRARY_PATH --- doc/techref/environment_variables.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/techref/environment_variables.md b/doc/techref/environment_variables.md index bf93c028e05..510f9cb0df6 100644 --- a/doc/techref/environment_variables.md +++ b/doc/techref/environment_variables.md @@ -2,7 +2,7 @@ Several environment variables can be used to control the behavior of PyGMT. These environment variables can be set in your shell or in your Python script using the -`os.environ` dictionary. +:py:data:`os.environ` dictionary. Here we list the environment variables that are used by PyGMT. The environment variables are divided into three categories: system environment variables, GMT/PyGMT @@ -20,6 +20,9 @@ TZ ## GMT/PyGMT Environment Variables ```{glossary} +GMT_LIBRARY_PATH + Directory to the GMT library. + PYGMT_USE_EXTERNAL_DISPLAY Setting this environment variable to `"false"` can disable image preview in external viewers. It's useful when running the tests and building the documentation From 2be65fa67df0c699a5e9f275ae38ea873d813909 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 14 Sep 2024 14:34:35 +0800 Subject: [PATCH 5/8] Add references to GMT_LIBRARY_PATH --- doc/install.md | 8 ++++---- pygmt/clib/loading.py | 4 ++-- pygmt/clib/session.py | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) 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/pygmt/clib/loading.py b/pygmt/clib/loading.py index 60541c7186d..ced50bc53fe 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,7 +128,7 @@ 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 + 1. Path defined by environmental variable :term:`GMT_LIBRARY_PATH` 2. Path returned by command "gmt --show-library" 3. Path defined by environmental variable PATH (Windows only) 4. System default search path diff --git a/pygmt/clib/session.py b/pygmt/clib/session.py index a0c11373d68..075ee76f255 100644 --- a/pygmt/clib/session.py +++ b/pygmt/clib/session.py @@ -109,7 +109,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 From e9608474eae2d92fa55fa34f150956fbb8e5fdfa Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sat, 14 Sep 2024 14:34:49 +0800 Subject: [PATCH 6/8] Improve the description of the variables --- doc/techref/environment_variables.md | 37 +++++++++++++++++----------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/doc/techref/environment_variables.md b/doc/techref/environment_variables.md index 510f9cb0df6..39c0cb8943a 100644 --- a/doc/techref/environment_variables.md +++ b/doc/techref/environment_variables.md @@ -1,38 +1,47 @@ # Environmental Variables -Several environment variables can be used to control the behavior of PyGMT. These -environment variables can be set in your shell or in your Python script using the +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 that are used by PyGMT. The environment -variables are divided into three categories: system environment variables, GMT/PyGMT -environment variables, and module-specific environment variables. +Here we list the environment variables used by PyGMT. The environment variables 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. Refer to the - [Specifying the Time Zone with TZ](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html) - for the valid format. + 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 the [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 - Directory to the GMT library. + 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 - Setting this environment variable 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. + 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 the x2sys-related functions (e.g., - {func}`pygmt.x2sys_init`) can keep track of the x2sys settings. + 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. ``` From 7ed130002bca93095e3aa89870b1848cc8c3fd95 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 15 Sep 2024 23:55:34 +0800 Subject: [PATCH 7/8] Fix the link to os.environ --- doc/techref/environment_variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/techref/environment_variables.md b/doc/techref/environment_variables.md index 39c0cb8943a..74b8ce72e3e 100644 --- a/doc/techref/environment_variables.md +++ b/doc/techref/environment_variables.md @@ -2,7 +2,7 @@ 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. +{py:data}`os.environ` dictionary. Here we list the environment variables used by PyGMT. The environment variables are categorized into three groups: From ef76a1a7586b028e40d8b2b2fc64699d82c000c7 Mon Sep 17 00:00:00 2001 From: Dongdong Tian Date: Sun, 22 Sep 2024 20:29:12 +0800 Subject: [PATCH 8/8] Change "environmental" to "environment" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com> --- doc/techref/environment_variables.md | 7 +++---- pygmt/clib/loading.py | 6 +++--- pygmt/src/x2sys_init.py | 2 +- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/techref/environment_variables.md b/doc/techref/environment_variables.md index 74b8ce72e3e..cc0ab0605a7 100644 --- a/doc/techref/environment_variables.md +++ b/doc/techref/environment_variables.md @@ -1,11 +1,10 @@ -# Environmental Variables +# 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. The environment variables are -categorized into three groups: +Here we list the environment variables used by PyGMT which are categorized into three groups: 1. System environment variables 2. GMT/PyGMT environment variables @@ -17,7 +16,7 @@ categorized into three groups: 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 the [Specifying the Time Zone with TZ](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html) + 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. ``` diff --git a/pygmt/clib/loading.py b/pygmt/clib/loading.py index ced50bc53fe..7034bf103df 100644 --- a/pygmt/clib/loading.py +++ b/pygmt/clib/loading.py @@ -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 :term:`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/src/x2sys_init.py b/pygmt/src/x2sys_init.py index fae77a39af6..99af7211424 100644 --- a/pygmt/src/x2sys_init.py +++ b/pygmt/src/x2sys_init.py @@ -30,7 +30,7 @@ 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 variable + 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.