Merge branch 'master' into reffig_by_call_module

Author: seisman

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -13,23 +13,19 @@ assignees: ''
 **Before release**:
 - [ ] Reserve a DOI on [Zenodo](https://zenodo.org) by clicking on "New Version"
 - [ ] Update Changelog
+- [ ] Add a new entry in `doc/_static/version_switch.js` for documentation switcher
 
 **Release**:
-- [ ] Make a tag and push it to Github
-```
-git tag vX.Y.Z
-git push --tags
-```
-- [ ] Go to [GitHub Release](https://github.com/GenericMappingTools/pygmt/releases) and make a release
+- [ ] Go to [GitHub Release](https://github.com/GenericMappingTools/pygmt/releases) and make a release, this will automatically create a tag too
 - [ ] Manually upload the pygmt-vX.Y.Z.zip file to https://zenodo.org/deposit, make sure you file it under the correct reserved DOI
-- [ ] Announce the releases on the GMT [forum](https://forum.generic-mapping-tools.org/c/news/), [website](https://github.com/GenericMappingTools/website) (News) and [ResearchGate](https://www.researchgate.net/project/PyGMT-A-Python-interface-for-the-Generic-Mapping-Tools)
 
 **After release**:
-- [ ] Create branch 0.x for bug-fixes if this is a minor release (i.e. create branch 0.1 after 0.1.0 is released)
-- [ ] Commit changes to Github
-
-**3rd party update**:
 - [ ] Update conda-forge [pygmt-feedstock](https://github.com/conda-forge/pygmt-feedstock) [Usually done automatically by conda-forge's bot]
+- [ ] Bump PyGMT version on https://github.com/GenericMappingTools/try-gmt
+- [ ] Announce the release on:
+  - [ ] GMT [forum](https://forum.generic-mapping-tools.org/c/news/)
+  - [ ] [Major/Minor releases only] GMT [website](https://github.com/GenericMappingTools/website) (News)
+  - [ ] [ResearchGate](https://www.researchgate.net/project/PyGMT-A-Python-interface-for-the-Generic-Mapping-Tools)
 
 ---
 

MAINTENANCE.md

@@ -154,17 +154,13 @@ Open `index.html` and check for any flaws or error messages.
 
 ### Pushing to PyPI and updating the documentation
 
-After the changelog is updated, making a release should be as simple as creating a new
-git tag and pushing it to Github:
+After the changelog is updated, making a release can be done by going to
+https://github.com/GenericMappingTools/pygmt/releases, editing the draft release,
+and clicking on publish. A git tag will also be created, make sure that this
+tag is a proper version number (following [Semantic Versioning](https://semver.org/))
+with a leading `v`. E.g. `v0.2.1`.
 
-```bash
-git tag v0.2.0
-git push --tags
-```
-
-The tag should be version number (following [Semantic Versioning](https://semver.org/))
-with a leading `v`.
-This should trigger Travis to do all the work for us.
+Once the release/tag is created, this should trigger Travis to do all the work for us.
 A new source distribution will be uploaded to PyPI, a new folder with the documentation
 HTML will be pushed to *gh-pages*, and the `latest` link will be updated to point to
 this new folder.

Makefile

@@ -6,8 +6,8 @@ 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
-FLAKE8_FILES=$(PROJECT) setup.py
-LINT_FILES=$(PROJECT) setup.py
+FLAKE8_FILES=$(PROJECT) setup.py doc/conf.py
+LINT_FILES=$(PROJECT) setup.py doc/conf.py
 
 help:
 	@echo "Commands:"
@@ -47,7 +47,8 @@ lint:
 clean:
 	find . -name "*.pyc" -exec rm -v {} \;
 	find . -name "*~" -exec rm -v {} \;
-	rm -rvf build dist MANIFEST *.egg-info __pycache__ .coverage .cache htmlcov coverage.xml
+	find . -type d -name  "__pycache__" -exec rm -rv {} +
+	rm -rvf build dist MANIFEST *.egg-info .coverage .cache htmlcov coverage.xml
 	rm -rvf $(TESTDIR)
 	rm -rvf baseline
 	rm -rvf result_images

README.rst

@@ -73,7 +73,7 @@ Project goals
 * Build a Pythonic API for GMT.
 * Interface with the GMT C API directly using ctypes (no system calls).
 * Support for rich display in the Jupyter notebook.
-* Integration with the Scipy stack: numpy.ndarray or pandas.DataFrame for data tables
+* Integration with the PyData Ecosystem: numpy.ndarray or pandas.DataFrame for data tables
   and xarray.DataArray for grids.
 
 

doc/Makefile

@@ -21,7 +21,7 @@ help:
 	@echo "  doctest    run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	rm -rf $(BUILDDIR)/html/*
+	rm -rf $(BUILDDIR)/html
 	rm -rf $(BUILDDIR)/doctrees
 	rm -rf $(BUILDDIR)/linkcheck
 	rm -rf modules

doc/_static/version_switch.js

@@ -0,0 +1,79 @@
+// Copyright 2013 PSF. Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+// File originates from the cpython source found in Doc/tools/sphinxext/static/version_switch.js
+
+(function() {
+  'use strict';
+
+  var doc_url = "www.pygmt.org";
+  //var doc_url = "0.0.0.0:8000"; // for local testing only
+  var url_re = new RegExp(doc_url + "\\/(dev|latest|(v\\d+\\.\\d+\\.\\d+))\\/");
+  // List all versions.
+  // Add one entry "version: title" for any minor releases
+  var all_versions = {
+    'latest': 'latest',
+    'dev': 'dev',
+    'v0.2.0': 'v0.2.0',
+    'v0.1.2': 'v0.1.2',
+    'v0.1.1': 'v0.1.1',
+    'v0.1.0': 'v0.1.0',
+    '0.0.1a0': 'v0.0.1a0',
+  };
+
+  function build_select(current_version, current_release) {
+    var buf = ['<select>'];
+
+    $.each(all_versions, function(version, title) {
+      buf.push('<option value="' + version + '"');
+      if (version == current_version) {
+        buf.push(' selected="selected">');
+        if (version == "latest" || version == "dev") {
+          buf.push(title + ' (' + current_release + ')');
+        } else {
+          buf.push(current_version);
+        }
+      } else {
+        buf.push('>' + title);
+      }
+      buf.push('</option>');
+    });
+
+    buf.push('</select>');
+    return buf.join('');
+  }
+
+  function patch_url(url, new_version) {
+    return url.replace(url_re, doc_url + '/' + new_version + '/');
+  }
+
+  function on_switch() {
+    var selected = $(this).children('option:selected').attr('value');
+
+    var url = window.location.href,
+        new_url = patch_url(url, selected);
+
+    if (new_url != url) {
+      // check beforehand if url exists, else redirect to version's start page
+      $.ajax({
+        url: new_url,
+        success: function() {
+           window.location.href = new_url;
+        },
+        error: function() {
+            window.location.href = 'http://' + doc_url + '/' + selected;
+        }
+      });
+    }
+  }
+
+  $(document).ready(function() {
+    var match = url_re.exec(window.location.href);
+    if (match) {
+      var release = DOCUMENTATION_OPTIONS.VERSION;
+      var version = match[1];
+      var select = build_select(version, release);
+      $('.version_switch_note').html('Or, select a version from the drop-down menu above.');
+      $('.version').html(select);
+      $('.version select').bind('change', on_switch);
+    }
+  });
+})();

doc/_templates/layout.html

@@ -15,6 +15,10 @@
       ga('set', 'anonymizeIp', true);
       ga('send', 'pageview');
     </script>
+
+    <!-- Documentation switcher -->
+    <!-- Point to the *dev* version switcher. This will allow the latest versions to appear on older documentation. -->
+    <script type="text/javascript" src="/dev/_static/version_switch.js"></script>
 {% endblock %}
 
 

doc/conf.py

@@ -1,12 +1,14 @@
 # -*- coding: utf-8 -*-
-import sys
-import os
-import glob
-import shutil
+"""
+Sphinx documentation configuration file.
+"""
+# pylint: disable=invalid-name
+
 import datetime
-import sphinx_rtd_theme
-import sphinx_gallery
-from sphinx_gallery.sorting import FileNameSortKey, ExplicitOrder
+from sphinx_gallery.sorting import (  # pylint: disable=no-name-in-module
+    FileNameSortKey,
+    ExplicitOrder,
+)
 from pygmt import __version__, __commit__
 from pygmt.sphinx_gallery import PyGMTScraper
 
@@ -60,6 +62,7 @@
     "gallery_dirs": ["gallery", "tutorials", "projections"],
     "subsection_order": ExplicitOrder(
         [
+            "../examples/gallery/line",
             "../examples/gallery/coast",
             "../examples/gallery/plot",
             "../examples/gallery/grid",
@@ -90,18 +93,20 @@
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 source_suffix = ".rst"
+needs_sphinx = "1.8"
 # The encoding of source files.
 source_encoding = "utf-8-sig"
 master_doc = "index"
 
 # General information about the project
 year = datetime.date.today().year
 project = "PyGMT"
-copyright = "2017-{}, The PyGMT Developers.".format(year)
+copyright = f"2017-{year}, The PyGMT Developers."  # pylint: disable=redefined-builtin
 if len(__version__.split("+")) > 1 or __version__ == "unknown":
     version = "dev"
 else:
     version = __version__
+release = __version__
 
 # These enable substitutions using |variable| in the rst files
 rst_epilog = """
@@ -116,6 +121,7 @@
 html_logo = ""
 html_favicon = "_static/favicon.png"
 html_static_path = ["_static"]
+html_css_files = ["style.css"]
 html_extra_path = []
 pygments_style = "default"
 add_function_parentheses = False
@@ -127,28 +133,29 @@
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {}
 repository = "GenericMappingTools/pygmt"
-commit_link = f'<a href="https://github.com/GenericMappingTools/pygmt/commit/{ __commit__ }">{ __commit__[:7] }</a>'
+repository_url = "https://github.com/GenericMappingTools/pygmt"
+commit_link = f'<a href="{repository_url}/commit/{ __commit__ }">{ __commit__[:7] }</a>'
 html_context = {
     "menu_links": [
         (
             '<i class="fa fa-users fa-fw"></i> Contributing',
-            "https://github.com/GenericMappingTools/pygmt/blob/master/CONTRIBUTING.md",
+            f"{repository_url}/blob/master/CONTRIBUTING.md",
         ),
         (
             '<i class="fa fa-gavel fa-fw"></i> Code of Conduct',
-            "https://github.com/GenericMappingTools/pygmt/blob/master/CODE_OF_CONDUCT.md",
+            f"{repository_url}/blob/master/CODE_OF_CONDUCT.md",
         ),
         (
             '<i class="fa fa-book fa-fw"></i> License',
-            "https://github.com/GenericMappingTools/pygmt/blob/master/LICENSE.txt",
+            f"{repository_url}/blob/master/LICENSE.txt",
         ),
         (
             '<i class="fa fa-comment fa-fw"></i> Contact',
             "https://forum.generic-mapping-tools.org",
         ),
         (
             '<i class="fa fa-github fa-fw"></i> Source Code',
-            "https://github.com/GenericMappingTools/pygmt",
+            repository_url,
         ),
     ],
     # Custom variables to enable "Improve this page"" and "Download notebook"
@@ -162,8 +169,3 @@
     "github_version": "master",
     "commit": commit_link,
 }
-
-
-# Load the custom CSS files (needs sphinx >= 1.6 for this to work)
-def setup(app):
-    app.add_stylesheet("style.css")

doc/overview.rst

@@ -49,13 +49,13 @@ These are conference presentations about the development of PyGMT (previously
 * "Building an object-oriented Python interface for the Generic Mapping Tools".
   2018.
   Leonardo Uieda and Paul Wessel.
-  Presented at *Scipy 2018*.
+  Presented at *SciPy 2018*.
   doi:`10.6084/m9.figshare.6814052 <https://doi.org/10.6084/m9.figshare.6814052>`__
 
 .. figure:: _static/scipy2018-youtube-thumbnail.png
    :target: https://www.youtube.com/watch?v=6wMtfZXfTRM
    :align: center
-   :alt: Scipy youtube video
+   :alt: SciPy youtube video
 
 * "Integrating the Generic Mapping Tools with the Scientific Python Ecosystem".
   2018.
@@ -71,13 +71,13 @@ These are conference presentations about the development of PyGMT (previously
 * "Bringing the Generic Mapping Tools to Python".
   2017.
   Leonardo Uieda and Paul Wessel.
-  Presented at *Scipy 2017*.
+  Presented at *SciPy 2017*.
   doi:`10.6084/m9.figshare.7635833 <https://doi.org/10.6084/m9.figshare.7635833>`__
 
 .. figure:: _static/scipy2017-youtube-thumbnail.png
    :target: https://www.youtube.com/watch?v=93M4How7R24
    :align: center
-   :alt: Scipy youtube video
+   :alt: SciPy youtube video
 
 * "A modern Python interface for the Generic Mapping Tools".
   2017.

examples/gallery/line/README.txt

@@ -0,0 +1,2 @@
+Lines
+-----

examples/gallery/line/linestyles.py

@@ -0,0 +1,42 @@
+"""
+Line styles
+-----------
+
+The :meth:`pygmt.Figure.plot` method can plot lines in different styles.
+The default line style is a 0.25-point wide, black, solid line, and can be
+customized via the ``pen`` argument.
+
+A *pen* in GMT has three attributes: *width*, *color*, and *style*.
+The *style* attribute controls the appearance of the line.
+Giving “dotted” or “.” yields a dotted line, whereas a dashed pen is requested
+with “dashed” or “-”. Also combinations of dots and dashes, like “.-” for a
+dot-dashed line, are allowed.
+
+For more advanced *pen* attributes, see the GMT cookbook
+:gmt-docs:`cookbook/features.html#wpen-attrib`.
+
+"""
+
+import numpy as np
+import pygmt
+
+# Generate a sample line for plotting
+x = np.linspace(0, 10, 500)
+y = np.sin(x)
+
+fig = pygmt.Figure()
+fig.basemap(region=[0, 10, -3, 3], projection="X15c/8c", frame=["xaf", "yaf", "WSrt"])
+
+# Plot the line using the default line style
+fig.plot(x=x, y=y)
+
+# Plot the lines using different line styles
+fig.plot(x=x, y=y + 1.5, pen="1p,red,-")
+fig.plot(x=x, y=y + 1.0, pen="2p,blue,.")
+fig.plot(x=x, y=y + 0.5, pen="1p,red,-.")
+
+fig.plot(x=x, y=y - 0.5, pen="2p,blue,..-")
+fig.plot(x=x, y=y - 1.0, pen="3p,tomato,--.")
+fig.plot(x=x, y=y - 1.5, pen="3p,tomato,4_2:2p")
+
+fig.show()