Merge branch 'master' into newfeature_xyz2grd

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,7 +4,7 @@
 
 <!-- Please describe changes proposed and **why** you made them. If unsure, open an issue first so we can discuss.-->
 
-<!-- If fixing an issue, put the issue number after the # below (no spaces). Github will automatically close it when this gets merged. -->
+<!-- If fixing an issue, put the issue number after the # below (no spaces). GitHub will automatically close it when this gets merged. -->
 Fixes #
 
 
@@ -15,3 +15,7 @@ Fixes #
 - [ ] Add new public functions/methods/classes to `doc/api/index.rst`.
 - [ ] Write detailed docstrings for all functions/methods.
 - [ ] If adding new functionality, add an example to docstrings or tutorials.
+
+**Notes**
+
+- You can write `/format` in the first line of a comment to lint the code automatically

.github/workflows/cache_data.yaml

@@ -37,8 +37,8 @@ jobs:
                         @tut_bathy.nc @tut_quakes.ngdc @tut_ship.xyz \
                         @usgs_quakes_22.txt
 
-      # Upload the downloaded files as artifacts to Github
-      - name: Upload artifacts to Github
+      # Upload the downloaded files as artifacts to GitHub
+      - name: Upload artifacts to GitHub
         uses: actions/upload-artifact@v2
         with:
           name: gmt-cache

.github/workflows/ci_tests.yaml

@@ -28,7 +28,7 @@ jobs:
           python-version: 3.7
 
       - name: Install packages
-        run: pip install black flake8 pylint
+        run: pip install black blackdoc flake8 pylint
 
       - name: Formatting check (black and flake8)
         run: make check
@@ -89,8 +89,8 @@ jobs:
         shell: bash -l {0}
         run: conda list
 
-      # Download cached remote files (artifacts) from Github
-      - name: Download remote data from Github
+      # Download cached remote files (artifacts) from GitHub
+      - name: Download remote data from GitHub
         uses: dawidd6/[email protected]
         with:
           workflow: cache_data.yaml

.github/workflows/ci_tests_dev.yaml

@@ -21,7 +21,7 @@ jobs:
       matrix:
         python-version: [3.8]
         os: [ubuntu-20.04, macOS-10.15]
-        gmt_git_ref: [6.1, master]
+        gmt_git_ref: [master]
     env:
       # LD_LIBRARY_PATH: ${{ github.workspace }}/gmt/lib:$LD_LIBRARY_PATH
       GMT_INSTALL_DIR: ${{ github.workspace }}/gmt-install-dir
@@ -61,8 +61,8 @@ jobs:
         env:
           GMT_GIT_REF: ${{ matrix.gmt_git_ref }}
 
-      # Download cached remote files (artifacts) from Github
-      - name: Download remote data from Github
+      # Download cached remote files (artifacts) from GitHub
+      - name: Download remote data from GitHub
         uses: dawidd6/[email protected]
         with:
           workflow: cache_data.yaml

.github/workflows/format-command.yml

@@ -0,0 +1,47 @@
+name: format-command
+on:
+  repository_dispatch:
+    types: [format-command]
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      # Generate token from GenericMappingTools bot
+      - uses: tibdex/github-app-token@v1
+        id: generate-token
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      # Checkout the pull request branch
+      - uses: actions/checkout@v2
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          repository: ${{ github.event.client_payload.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.client_payload.pull_request.head.ref }}
+
+      # Setup Python environment
+      - uses: actions/setup-python@v1
+
+      # Install formatting tools
+      - name: Install formatting tools
+        run: pip install black blackdoc flake8
+
+      # Run "make format" and commit the change to the PR branch
+      - name: Commit to the PR branch if any changes
+        run: |
+          make format
+          if [[ $(git ls-files -m) ]]; then
+            git config --global user.name 'actions-bot'
+            git config --global user.email '[email protected]'
+            git commit -am "[format-command] fixes"
+            git push
+          fi
+
+      - name: Add reaction
+        uses: peter-evans/create-or-update-comment@v1
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          repository: ${{ github.event.client_payload.github.payload.repository.full_name }}
+          comment-id: ${{ github.event.client_payload.github.payload.comment.id }}
+          reaction-type: hooray

.github/workflows/slash-command-dispatch.yml

@@ -0,0 +1,24 @@
+name: Slash Command Dispatch
+on:
+  issue_comment:
+    types: [created]
+    # Add "edited" type for test purposes. Where possible, avoid using to prevent processing unnecessary events.
+    # types: [created, edited]
+jobs:
+  slashCommandDispatch:
+    runs-on: ubuntu-latest
+    steps:
+      # Generate token from GenericMappingTools bot
+      - uses: tibdex/github-app-token@v1
+        id: generate-token
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Slash Command Dispatch
+        uses: peter-evans/slash-command-dispatch@v2
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          commands: |
+            format
+          issue-type: pull-request

.travis.yml

@@ -18,7 +18,7 @@ branches:
 env:
     global:
         # Encrypted variables
-        # Github Token for pushing the built docs (GH_TOKEN)
+        # GitHub Token for pushing the built docs (GH_TOKEN)
         - secure: "QII0477v0mmCCW3qSNXLCOtqraJaCICtSghiyrxYsuUdJTrXzXBNhX2KLIjcKYXOK1HdwYOFGf8xBVLl44clHlAW7R32ecEGeTJizr0yqTBvT3rNG1Xb7+E6jdXqrIs//PmPRaF8zOZxPl1SJKDK4jJpCx5HnAflg7wl/6tQLD6K3/dQ6FG2s3UKsc8o4qchOiEfxYhOuKo3jt2S0HdsNAQFw3mFHCCrclxDr3llSQtWSY0mirZnta7AI4nMvzxl2nUhdHEpxgzIjWxCWLAwmj3/NxLz0VSgNCtl2bNYk6AYrc5RcANGk2fcYaZr9mTU3Aax60S4389B39Pq95hBN21jYdbw9vCN810dYpTUk2siLysx8gF6r2JWEF8SskXlF79r3phtaFTMOS4GqeiuwjifZeaLAL/H1PTQFDDG/UKEwBpLuzrPMDw/84iRtyWKqWR/f14YdKhH4YAkcOuRglEXiI/1A0qWKiZ1iZfky8Tys+wN5nyss23w/JeYXVgBdTkNzvp3diFWK8+Wl9j3HYpX9LlEHJwASA1wHLL85t4ToymgLjo9gvLvwzB7T+fWNtEbh4ELbvI7jaKrvir8uSGYy4bGbfRclh5CktD//mTLhDyAsQDS8obF/Ri9mVqFzjK6417ORfu8qnpXU+mIHPRBoKvpS2WqnPtSwF8KPv8="
         # TWINE_PASSWORD to deploy to PyPI
         - secure: "md4fgPt9RC/sCoN5//5PcNHLUd9gWQGewV5hFpWW88MRTjxTng1Zfs8r7SqlF2AkEEepFfyzq0BEe9c3FMAnFbec3KmqdlQen4V8xDbLrcTlvkPlTrYGbAScUvdhhqojB//hMHoTD4KvxAv9CiUwFBO4hCMmj2buWHUbV9Ksu5WCW9mF/gkt/hIuYAU6Mbwt8PiYyMgUpzMHO1vruofcWRaVnvKwmBqHB0ae86D4/drpwn4CWjlM12WUnphT2bssiyPkw24FZtCN6kPVta6bLZKBxu0bZpw2vbXuUG+Yh19Q4mp8wNYT3XSHJf8Hl5LfujF48+cLWu+6rlCkdcelyVylhWLFc3rGOONAv4G8jWW2yNSz/bLQfJnMpd81fQEu5eySmFxB7mdB0uyKpvIG1jMJQ73LlYKakKLAPdYhMFyQAHoX9gvCE3S4QR95DBMi5gM/pZubOCcMLdjPHB5JKpJHSjxbOzyVwgmsUIEgd5Bi2vZvvYQXn1plk4xpQ3PhXc+/gi33bzY89mKcfOn0HJ2pD1vLqDXRCBsMCakoLZ0JB/6bacaz4FngbsGWuQ+I1cz20lJGL/MSi9bW1G7Uoidt3GXXWDmXrWt70vIXlLIxr8XV0Mu/rPbauGgWE+ZSYEfvdM5sP+FNF7vQ5de+Fkvzg5Z3tTfR+O1W+d7+vM4="

CONTRIBUTING.md

@@ -70,7 +70,7 @@ for the project where you can ask questions.
 
 ## Reporting a Bug
 
-Find the *Issues* tab on the top of the Github repository and click *New Issue*.
+Find the *Issues* tab on the top of the GitHub repository and click *New Issue*.
 You'll be prompted to choose between different types of issue, like bug reports and
 feature requests.
 Choose the one that best matches your need.
@@ -92,7 +92,7 @@ download and install anything:
 * On each documentation page, there should be an "Improve This Page" link at the very
   top.
 * Click on that link to open the respective source file (usually an `.rst` file in the
-  `doc` folder) on Github for editing online (you'll need a Github account).
+  `doc` folder) on GitHub for editing online (you'll need a GitHub account).
 * Make your desired changes.
 * When you're done, scroll to the bottom of the page.
 * Fill out the two fields under "Commit changes": the first is a short title describing
@@ -245,8 +245,8 @@ directory).
 
 ### Code style
 
-We use [Black](https://github.com/ambv/black) to format the code so we don't have to
-think about it.
+We use [Black](https://github.com/ambv/black) and [blackdoc](https://github.com/keewis/blackdoc)
+to format the code so we don't have to think about it.
 Black loosely follows the [PEP8](http://pep8.org) guide but with a few differences.
 Regardless, you won't have to worry about formatting the code yourself.
 Before committing, run it to automatically format your code:
@@ -255,17 +255,18 @@ Before committing, run it to automatically format your code:
 make format
 ```
 
-Don't worry if you forget to do it.
-Our continuous integration systems will warn us and you can make a new commit with the
-formatted code.
+Don't worry if you forget to do it. Our continuous integration systems will
+warn us and you can make a new commit with the formatted code.
+Even better, you can just write `/format` in the first line of any comment in a
+Pull Request to lint the code automatically.
 
 We also use [flake8](http://flake8.pycqa.org/en/latest/) and
 [pylint](https://www.pylint.org/) to check the quality of the code and quickly catch
 common errors.
 The [`Makefile`](Makefile) contains rules for running both checks:
 
 ```bash
-make check   # Runs flake8 and black (in check mode)
+make check   # Runs flake8, black and blackdoc (in check mode)
 make lint    # Runs pylint, which is a bit slower
 ```
 
@@ -308,6 +309,14 @@ in your browser. **Strive to get 100% coverage for the lines you changed.**
 It's OK if you can't or don't know how to test something.
 Leave a comment in the PR and we'll help you out.
 
+You can also run tests in just one test script using:
+
+    pytest --verbose --mpl --mpl-results-path=results --doctest_modules pygmt/tests/NAME_OF_TEST_FILE.py
+
+or run tests which contain names that match a specific keyword expression:
+
+    pytest --verbose --mpl --mpl-results-path=results --doctest_modules -k KEYWORD pygmt/tests
+
 ### Testing plots
 
 Writing an image-based test is only slightly more difficult than a simple test.
@@ -428,7 +437,7 @@ Some things that will increase the chance that your pull request is accepted qui
 
 Pull requests will automatically have tests run by TravisCI.
 This includes running both the unit tests as well as code linters.
-Github will show the status of these checks on the pull request.
+GitHub will show the status of these checks on the pull request.
 Try to get them all passing (green).
 If you have any trouble, leave a comment in the PR or
 [get in touch](#how-can-i-talk-to-you).

MAINTENANCE.md

@@ -11,7 +11,7 @@ If you want to make a contribution to the project, see the
 
 * *master*: Always tested and ready to become a new version. Don't push directly to this
   branch. Make a new branch and submit a pull request instead.
-* *gh-pages*: Holds the HTML documentation and is served by Github. Pages for the master
+* *gh-pages*: Holds the HTML documentation and is served by GitHub. Pages for the master
   branch are in the `dev` folder. Pages for each release are in their own folders.
   **Automatically updated by TravisCI** so you shouldn't have to make commits here.
 
@@ -40,12 +40,12 @@ The main advantages of this are:
 
 ## Continuous Integration
 
-We use Github Actions and TravisCI continuous integration (CI) services to
+We use GitHub Actions and TravisCI continuous integration (CI) services to
 build and test the project on Linux, macOS and Windows.
 They rely on the `requirements.txt` file to install required dependencies using
 conda and the `Makefile` to run the tests and checks.
 
-### Github Actions
+### GitHub Actions
 
 There are 3 configuration files located in `.github/workflows`:
 
@@ -59,7 +59,7 @@ It is also scheduled to run daily on the *master* branch.
 This is only triggered when a review is requested or re-requested on a PR.
 It is also scheduled to run daily on the *master* branch.
 
-3. `cache_data.yaml` (Caches GMT remote data files needed for Github Actions CI)
+3. `cache_data.yaml` (Caches GMT remote data files needed for GitHub Actions CI)
 
 This is scheduled to run every Sunday at 12 noon.
 If new remote files are needed urgently, maintainers can manually uncomment
@@ -85,7 +85,7 @@ submit pull requests to that repository.
 
 ## Continuous Documentation
 
-We use the [Zeit Now for Github integration](https://zeit.co/github) to preview changes
+We use the [Zeit Now for GitHub integration](https://zeit.co/github) to preview changes
 made to our documentation website every time we make a commit in a pull request.
 The integration service has a configuration file `now.json`, with a list of options to
 change the default behaviour at https://zeit.co/docs/configuration.
@@ -103,10 +103,10 @@ There are a few steps that still must be done manually, though.
 
 ### Updating the changelog
 
-The Release Drafter Github Action will automatically keep a draft changelog at
+The Release Drafter GitHub Action will automatically keep a draft changelog at
 https://github.com/GenericMappingTools/pygmt/releases, adding a new entry
 every time a Pull Request (with a proper label) is merged into the master branch.
-This release drafter tool has two configuration files, one for the Github Action
+This release drafter tool has two configuration files, one for the GitHub Action
 at .github/workflows/release-drafter.yml, and one for the changelog template
 at .github/release-drafter.yml. Configuration settings can be found at
 https://github.com/release-drafter/release-drafter.
@@ -122,7 +122,7 @@ publishing the actual release notes at https://www.pygmt.org/latest/changes.html
 
 2. Edit the changes list to remove any trivial changes (updates to the README, typo
    fixes, CI configuration, etc).
-3. Replace the PR number in the commit titles with a link to the Github PR page.
+3. Replace the PR number in the commit titles with a link to the GitHub PR page.
    Use ``sed -i.bak -E 's$\(#([0-9]*)\)$(`#\1 <https://github.com/GenericMappingTools/pygmt/pull/\1>`__)$g' changes.rst``
    to make the change automatically.
 4. Copy the remaining changes to `doc/changes.rst` under a new section for the
@@ -142,7 +142,7 @@ publishing the actual release notes at https://www.pygmt.org/latest/changes.html
 
 ### Check the README syntax
 
-Github is a bit forgiving when it comes to the RST syntax in the README but PyPI is not.
+GitHub is a bit forgiving when it comes to the RST syntax in the README but PyPI is not.
 So slightly broken RST can cause the PyPI page to not render the correct content. Check
 using the `rst2html.py` script that comes with docutils:
 
@@ -167,7 +167,7 @@ this new folder.
 
 ### Archiving on Zenodo
 
-Grab a zip file from the Github release and upload to Zenodo using the previously
+Grab a zip file from the GitHub release and upload to Zenodo using the previously
 reserved DOI.
 
 ### Updating the conda package

Makefile

@@ -6,6 +6,7 @@ PYTEST_ARGS=--cov=$(PROJECT) --cov-config=../.coveragerc \
 			--doctest-modules -v --mpl --mpl-results-path=results \
 			--pyargs ${PYTEST_EXTRA}
 BLACK_FILES=$(PROJECT) setup.py doc/conf.py examples
+BLACKDOC_OPTIONS=--line-length 79
 FLAKE8_FILES=$(PROJECT) setup.py doc/conf.py
 LINT_FILES=$(PROJECT) setup.py doc/conf.py
 
@@ -14,8 +15,8 @@ help:
 	@echo ""
 	@echo "  install   install in editable mode"
 	@echo "  test      run the test suite (including doctests) and report coverage"
-	@echo "  format    run black to automatically format the code"
-	@echo "  check     run code style and quality checks (black and flake8)"
+	@echo "  format    run black and blackdoc to automatically format the code"
+	@echo "  check     run code style and quality checks (black, blackdoc and flake8)"
 	@echo "  lint      run pylint for a deeper (and slower) quality check"
 	@echo "  clean     clean up build and generated files"
 	@echo ""
@@ -36,9 +37,11 @@ test:
 
 format:
 	black $(BLACK_FILES)
+	blackdoc $(BLACKDOC_OPTIONS) $(BLACK_FILES)
 
 check:
 	black --check $(BLACK_FILES)
+	blackdoc --check $(BLACKDOC_OPTIONS) $(BLACK_FILES)
 	flake8 $(FLAKE8_FILES)
 
 lint:

README.rst

@@ -38,6 +38,22 @@ PyGMT
 .. placeholder-for-doc-index
 
 
+Why PyGMT?
+----------
+
+A beautiful map is worth a thousand words.
+To truly understand how powerful PyGMT is, play with it online on `Binder <https://github.com/GenericMappingTools/try-gmt>`__!
+But if you need some convincing first, watch this **1 hour introduction** to PyGMT!
+
+Afterwards, feel free to look at our `Tutorials <https://www.pygmt.org/latest/tutorials>`__
+or visit the `PyGMT Gallery <https://www.pygmt.org/latest/gallery>`__.
+
+.. image:: https://user-images.githubusercontent.com/23487320/95393255-c0b72e80-0956-11eb-9471-24429461802b.png
+    :alt: Remote Online Sessions for Emerging Seismologists (ROSES): Unit 8 - PyGMT
+    :align: center
+    :target: https://www.youtube.com/watch?v=SSIGJEe0BIk
+
+
 Disclaimer
 ----------
 
@@ -50,7 +66,7 @@ implement new features. **This is not a finished product, use with caution.**
 
 We welcome any feedback and ideas!
 Let us know by submitting
-`issues on Github <https://github.com/GenericMappingTools/pygmt/issues>`__
+`issues on GitHub <https://github.com/GenericMappingTools/pygmt/issues>`__
 or by posting on our `Discourse forum <https://forum.generic-mapping-tools.org>`__.
 
 About
@@ -80,7 +96,7 @@ Project goals
 Contacting Us
 -------------
 
-* Most discussion happens `on Github
+* Most discussion happens `on GitHub
   <https://github.com/GenericMappingTools/pygmt>`__. Feel free to `open an issue
   <https://github.com/GenericMappingTools/pygmt/issues/new>`__ or comment on any
   open issue or pull request.
@@ -134,7 +150,7 @@ Who we are
 
 PyGMT is a community developed project. See the
 `AUTHORS.md <https://github.com/GenericMappingTools/pygmt/blob/master/AUTHORS.md>`__
-file on Github for a list of the people involved and a definition of the term "PyGMT
+file on GitHub for a list of the people involved and a definition of the term "PyGMT
 Developers".
 
 
@@ -170,7 +186,7 @@ Other Python wrappers for GMT:
 Documentation for other versions
 --------------------------------
 * `Development <https://www.pygmt.org/dev>`__ (reflects the *master* branch on
-  Github)
+  GitHub)
 * `Latest release <https://www.pygmt.org/latest>`__
 * `v0.2.0 <https://www.pygmt.org/v0.2.0>`__
 * `v0.1.2 <https://www.pygmt.org/v0.1.2>`__