diff --git a/.github/workflows/cache_data.yaml b/.github/workflows/cache_data.yaml index 259c1003ff3..1e63a4dcbd1 100644 --- a/.github/workflows/cache_data.yaml +++ b/.github/workflows/cache_data.yaml @@ -12,6 +12,9 @@ jobs: gmt_cache: name: Cache GMT artifacts runs-on: macOS-latest + defaults: + run: + shell: bash -l {0} steps: # Setup Miniconda @@ -23,12 +26,10 @@ jobs: # Install GMT - name: Install GMT - shell: bash -l {0} run: conda install -c conda-forge gmt=6.1.1 # Download remote files - name: Download remote data - shell: bash -l {0} run: | gmt which -Ga @earth_relief_10m_p @earth_relief_10m_g \ @earth_relief_30m_p @earth_relief_30m_g \ @@ -36,8 +37,8 @@ jobs: @earth_relief_05m_p @earth_relief_05m_g # Download one tile of the 03s srtm data. # @N35E135.earth_relief_03s_g.nc is for internal use only. - # The naming scheme may change. - # DO NOT USE IT IN SCRIPTS. + # The naming scheme may change. + # DO NOT USE IT IN SCRIPTS. gmt which -Ga @N35E135.earth_relief_03s_g.nc gmt which -Ga @ridge.txt @Table_5_11.txt @test.dat.nc \ @tut_bathy.nc @tut_quakes.ngdc @tut_ship.xyz \ diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml index 33d38f89123..bb94857c143 100644 --- a/.github/workflows/ci_tests.yaml +++ b/.github/workflows/ci_tests.yaml @@ -45,6 +45,9 @@ jobs: - os: ubuntu-latest python-version: 3.8 isDraft: true + defaults: + run: + shell: bash -l {0} # environmental variables used in coverage env: @@ -76,12 +79,10 @@ jobs: # Install GMT and other required dependencies from conda-forge - name: Install dependencies - shell: bash -l {0} run: conda env update --file environment.yml # Show installed pkg information for postmortem diagnostic - name: List installed packages - shell: bash -l {0} run: conda list # Download cached remote files (artifacts) from GitHub @@ -95,7 +96,6 @@ jobs: # Move downloaded files to ~/.gmt directory and list them - name: Move and list downloaded remote files - shell: bash -l {0} run: | mkdir -p ~/.gmt mv .gmt/* ~/.gmt @@ -105,21 +105,18 @@ jobs: # Install the package that we want to test - name: Install the package - shell: bash -l {0} run: | python setup.py sdist --formats=zip pip install dist/* # Install data version control (dvc) and pull data from dvc remote - name: Install dvc and pull data from dvc remote - shell: bash -l {0} run: | pip install dvc dvc pull # Run the tests - name: Test with pytest - shell: bash -l {0} run: make test PYTEST_EXTRA="-r P" # Upload diff images on test failure @@ -132,7 +129,6 @@ jobs: # Build the documentation - name: Build the documentation - shell: bash -l {0} run: make -C doc clean all # Upload coverage to Codecov diff --git a/.github/workflows/ci_tests_dev.yaml b/.github/workflows/ci_tests_dev.yaml index ea52ed95a38..aff7d457fe0 100644 --- a/.github/workflows/ci_tests_dev.yaml +++ b/.github/workflows/ci_tests_dev.yaml @@ -106,7 +106,6 @@ jobs: # Move downloaded files to ~/.gmt directory and list them - name: Move and list downloaded remote files - shell: bash -l {0} run: | mkdir -p ~/.gmt mv .gmt/* ~/.gmt diff --git a/doc/conf.py b/doc/conf.py index 9583ed7f8a4..25d044bdac4 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -9,7 +9,7 @@ # isort: off from sphinx_gallery.sorting import ( # pylint: disable=no-name-in-module ExplicitOrder, - FileNameSortKey, + ExampleTitleSortKey, ) from pygmt import __commit__, __version__ from pygmt.sphinx_gallery import PyGMTScraper @@ -71,10 +71,13 @@ "gallery_dirs": ["gallery", "tutorials", "projections"], "subsection_order": ExplicitOrder( [ - "../examples/gallery/line", - "../examples/gallery/coast", - "../examples/gallery/plot", - "../examples/gallery/grid", + "../examples/gallery/maps", + "../examples/gallery/lines", + "../examples/gallery/symbols", + "../examples/gallery/images", + "../examples/gallery/3d_plots", + "../examples/gallery/seismology", + "../examples/gallery/embellishments", "../examples/projections/azim", "../examples/projections/conic", "../examples/projections/cyl", @@ -88,7 +91,7 @@ # Remove the "Download all examples" button from the top level gallery "download_all_examples": False, # Sort gallery example by file name instead of number of lines (default) - "within_subsection_order": FileNameSortKey, + "within_subsection_order": ExampleTitleSortKey, # directory where function granular galleries are stored "backreferences_dir": "api/generated/backreferences", # Modules for which function level galleries are created. In diff --git a/doc/index.rst b/doc/index.rst index 7dcc11b8953..dbb64e0c822 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -38,7 +38,7 @@ tutorials/contour-map.rst tutorials/earth-relief.rst tutorials/3d-perspective-image.rst - tutorials/inset.rst + tutorials/insets.rst tutorials/subplots.rst tutorials/configuration.rst diff --git a/doc/install.rst b/doc/install.rst index 33b8cf695f1..f3e54a98994 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -29,7 +29,7 @@ To activate the virtual environment, you can do:: conda activate pygmt After this, check that everything works by running the following in a Python -interpreter (e.g. in a Jupyter notebook):: +interpreter (e.g., in a Jupyter notebook):: import pygmt pygmt.show_versions() @@ -40,8 +40,8 @@ Start by looking at the tutorials on our sidebar, good luck! .. note:: The sections below provide more detailed, step by step instructions to - installing and testing PyGMT for those who may have a slightly different - setup. + install and test PyGMT for those who may have a slightly different setup or + want to install the latest development version. Which Python? ------------- @@ -51,9 +51,10 @@ work, but there is no guarantee that PyGMT will behave as expected. We recommend using the `Anaconda `__ Python distribution to ensure you have all dependencies installed and the -``conda`` package manager available. -Installing Anaconda does not require administrative rights to your computer and -doesn't interfere with any other Python installations in your system. +`conda `__ +package manager is available. Installing Anaconda does not require administrative +rights to your computer and doesn't interfere with any other Python +installations on your system. Which GMT? @@ -110,14 +111,14 @@ Now we can create a new conda environment with Python and all our dependencies installed (we'll call it ``pygmt`` but feel free to change it to whatever you want):: - conda create --name pygmt python=3.9 pip numpy pandas xarray netcdf4 packaging gmt + conda create --name pygmt python=3.9 numpy pandas xarray netcdf4 packaging gmt Activate the environment by running the following (**do not forget this step!**):: conda activate pygmt From now on, all commands will take place inside the conda virtual environment -called 'pygmt' and won't affect your default 'base' installation. +called ``pygmt`` and won't affect your default ``base`` installation. Installing PyGMT @@ -134,6 +135,10 @@ This installs the latest stable release of PyGMT from conda install pygmt +This upgrades the installed PyGMT version to be the latest stable release:: + + conda update pygmt + Using pip ~~~~~~~~~ @@ -147,13 +152,11 @@ Alternatively, you can install the latest development version from pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt -or from PyGMT's `GitHub repository `__ -(slower as it downloads the whole archive):: - - pip install git+https://github.com/GenericMappingTools/pygmt.git#egg=pygmt +To upgrade the installed stable release or development version to be the latest +one, just add ``--upgrade`` to the corresponding command above. -Any of the above methods (conda/pip) should allow you to use the ``pygmt`` -library from Python. +Any of the above methods (conda/pip) should allow you to use the PyGMT package +from Python. Testing your install @@ -182,7 +185,8 @@ dependencies as well (be sure to have your conda environment activated):: conda install pytest pytest-mpl ipython -Test your installation by running the following inside a Python interpreter:: +Test your installation by running the following inside a Python interpreter +(note that it may take a few minutes):: import pygmt pygmt.show_versions() @@ -193,14 +197,14 @@ Finding the GMT shared library ------------------------------ Sometimes, PyGMT will be unable to find the correct version of the GMT shared -library. +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. This should be set to the directory where ``libgmt.so``, ``libgmt.dylib`` or -``gmt.dll`` can be found for Linux, macOS and Windows respectively. -e.g. on a command line, run:: +``gmt.dll`` can be found for Linux, macOS and Windows, respectively. +e.g., on a command line, run:: # Linux/macOS export GMT_LIBRARY_PATH=$HOME/anaconda3/envs/pygmt/lib diff --git a/examples/gallery/3d_plots/README.txt b/examples/gallery/3d_plots/README.txt new file mode 100644 index 00000000000..580c258215f --- /dev/null +++ b/examples/gallery/3d_plots/README.txt @@ -0,0 +1,2 @@ +3D Plots +-------- diff --git a/examples/gallery/grid/grdview_surface.py b/examples/gallery/3d_plots/grdview_surface.py similarity index 100% rename from examples/gallery/grid/grdview_surface.py rename to examples/gallery/3d_plots/grdview_surface.py diff --git a/examples/gallery/plot/scatter3d.py b/examples/gallery/3d_plots/scatter3d.py similarity index 100% rename from examples/gallery/plot/scatter3d.py rename to examples/gallery/3d_plots/scatter3d.py diff --git a/examples/gallery/coast/README.txt b/examples/gallery/coast/README.txt deleted file mode 100644 index a45d2747e61..00000000000 --- a/examples/gallery/coast/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Coastlines and boundaries -------------------------- diff --git a/examples/gallery/embellishments/README.txt b/examples/gallery/embellishments/README.txt new file mode 100644 index 00000000000..3a6e2b21482 --- /dev/null +++ b/examples/gallery/embellishments/README.txt @@ -0,0 +1,2 @@ +Plot embellishments +------------------- diff --git a/examples/gallery/plot/colorbar.py b/examples/gallery/embellishments/colorbar.py similarity index 100% rename from examples/gallery/plot/colorbar.py rename to examples/gallery/embellishments/colorbar.py diff --git a/examples/gallery/plot/inset.py b/examples/gallery/embellishments/inset.py similarity index 100% rename from examples/gallery/plot/inset.py rename to examples/gallery/embellishments/inset.py diff --git a/examples/gallery/plot/legend.py b/examples/gallery/embellishments/legend.py similarity index 100% rename from examples/gallery/plot/legend.py rename to examples/gallery/embellishments/legend.py diff --git a/examples/gallery/plot/logo.py b/examples/gallery/embellishments/logo.py similarity index 100% rename from examples/gallery/plot/logo.py rename to examples/gallery/embellishments/logo.py diff --git a/examples/gallery/grid/README.txt b/examples/gallery/grid/README.txt deleted file mode 100644 index 6fd2c9aea1a..00000000000 --- a/examples/gallery/grid/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Grids ------ diff --git a/examples/gallery/images/README.txt b/examples/gallery/images/README.txt new file mode 100644 index 00000000000..3375172a820 --- /dev/null +++ b/examples/gallery/images/README.txt @@ -0,0 +1,2 @@ +Images, contours, and fields +---------------------------- diff --git a/examples/gallery/plot/image.py b/examples/gallery/images/image.py similarity index 100% rename from examples/gallery/plot/image.py rename to examples/gallery/images/image.py diff --git a/examples/gallery/grid/track_sampling.py b/examples/gallery/images/track_sampling.py similarity index 100% rename from examples/gallery/grid/track_sampling.py rename to examples/gallery/images/track_sampling.py diff --git a/examples/gallery/line/README.txt b/examples/gallery/line/README.txt deleted file mode 100644 index 043f6ca6a79..00000000000 --- a/examples/gallery/line/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Lines ------ diff --git a/examples/gallery/lines/README.txt b/examples/gallery/lines/README.txt new file mode 100644 index 00000000000..8e2076a6c6d --- /dev/null +++ b/examples/gallery/lines/README.txt @@ -0,0 +1,2 @@ +Lines and vectors +----------------- diff --git a/examples/gallery/line/line-custom-cpt.py b/examples/gallery/lines/line_custom_cpt.py similarity index 100% rename from examples/gallery/line/line-custom-cpt.py rename to examples/gallery/lines/line_custom_cpt.py diff --git a/examples/gallery/line/linestyles.py b/examples/gallery/lines/linestyles.py similarity index 100% rename from examples/gallery/line/linestyles.py rename to examples/gallery/lines/linestyles.py diff --git a/examples/gallery/line/vector-heads-tails.py b/examples/gallery/lines/vector_heads_tails.py similarity index 98% rename from examples/gallery/line/vector-heads-tails.py rename to examples/gallery/lines/vector_heads_tails.py index 366ee58beda..7c213f73006 100644 --- a/examples/gallery/line/vector-heads-tails.py +++ b/examples/gallery/lines/vector_heads_tails.py @@ -26,7 +26,7 @@ In the following we use the :meth:`pygmt.Figure.plot` method to plot vectors with individual heads and tails. We must specify the modifiers (together with the vector type, here ``v``, see also -:doc:`Vector types documentation `) +:doc:`Vector types documentation `) by passing the corresponding shortcuts to the ``style`` parameter. """ diff --git a/examples/gallery/line/vectors.py b/examples/gallery/lines/vectors.py similarity index 96% rename from examples/gallery/line/vectors.py rename to examples/gallery/lines/vectors.py index 480cd9cb89b..7dc6d7042f9 100644 --- a/examples/gallery/line/vectors.py +++ b/examples/gallery/lines/vectors.py @@ -4,7 +4,7 @@ The :meth:`pygmt.Figure.plot` method can plot Cartesian, circular, and geographic vectors. The ``style`` parameter controls vector attributes. See also -:doc:`Vector attributes documentation `. +:doc:`Vector attributes documentation `. """ import numpy as np diff --git a/examples/gallery/maps/README.txt b/examples/gallery/maps/README.txt new file mode 100644 index 00000000000..b1a00a492fb --- /dev/null +++ b/examples/gallery/maps/README.txt @@ -0,0 +1,2 @@ +Maps and map elements +--------------------- diff --git a/examples/gallery/coast/borders.py b/examples/gallery/maps/borders.py similarity index 100% rename from examples/gallery/coast/borders.py rename to examples/gallery/maps/borders.py diff --git a/examples/gallery/coast/land_and_water.py b/examples/gallery/maps/land_and_water.py similarity index 100% rename from examples/gallery/coast/land_and_water.py rename to examples/gallery/maps/land_and_water.py diff --git a/examples/gallery/coast/shorelines.py b/examples/gallery/maps/shorelines.py similarity index 100% rename from examples/gallery/coast/shorelines.py rename to examples/gallery/maps/shorelines.py diff --git a/examples/gallery/plot/README.txt b/examples/gallery/plot/README.txt deleted file mode 100644 index c213e06feea..00000000000 --- a/examples/gallery/plot/README.txt +++ /dev/null @@ -1,2 +0,0 @@ -Plotting map items ------------------- diff --git a/examples/gallery/seismology/README.txt b/examples/gallery/seismology/README.txt new file mode 100644 index 00000000000..9f247d8f474 --- /dev/null +++ b/examples/gallery/seismology/README.txt @@ -0,0 +1,2 @@ +Seismology and geodesy +---------------------- diff --git a/examples/gallery/plot/meca.py b/examples/gallery/seismology/meca.py similarity index 100% rename from examples/gallery/plot/meca.py rename to examples/gallery/seismology/meca.py diff --git a/examples/gallery/symbols/README.txt b/examples/gallery/symbols/README.txt new file mode 100644 index 00000000000..8d8d751404e --- /dev/null +++ b/examples/gallery/symbols/README.txt @@ -0,0 +1,2 @@ +Symbols and markers +------------------- diff --git a/examples/gallery/plot/datetime-inputs.py b/examples/gallery/symbols/datetime_inputs.py similarity index 100% rename from examples/gallery/plot/datetime-inputs.py rename to examples/gallery/symbols/datetime_inputs.py diff --git a/examples/gallery/plot/multi-parameter-symbols.py b/examples/gallery/symbols/multi_parameter_symbols.py similarity index 100% rename from examples/gallery/plot/multi-parameter-symbols.py rename to examples/gallery/symbols/multi_parameter_symbols.py diff --git a/examples/gallery/plot/points.py b/examples/gallery/symbols/points.py similarity index 100% rename from examples/gallery/plot/points.py rename to examples/gallery/symbols/points.py diff --git a/examples/gallery/plot/points-transparency.py b/examples/gallery/symbols/points_transparency.py similarity index 100% rename from examples/gallery/plot/points-transparency.py rename to examples/gallery/symbols/points_transparency.py diff --git a/examples/gallery/plot/scatter.py b/examples/gallery/symbols/scatter.py similarity index 100% rename from examples/gallery/plot/scatter.py rename to examples/gallery/symbols/scatter.py diff --git a/examples/tutorials/inset.py b/examples/tutorials/insets.py similarity index 100% rename from examples/tutorials/inset.py rename to examples/tutorials/insets.py diff --git a/examples/tutorials/lines.py b/examples/tutorials/lines.py index a7340371aee..c844367cacb 100644 --- a/examples/tutorials/lines.py +++ b/examples/tutorials/lines.py @@ -125,7 +125,7 @@ # example below, the line width is set to ``7p``, the color is set to ``green``, and the # line style is ``-.-`` (*dash dot dash*). # -# For a gallery showing other ``pen`` settings, see :doc:`/gallery/line/linestyles`. +# For a gallery showing other ``pen`` settings, see :doc:`/gallery/lines/linestyles`. fig = pygmt.Figure() fig.plot(