Merge pull request #101 from lukelbd/proplotrc-changes

.proplotrc changes and related improvements

Author: lukelbd

.gitignore

@@ -3,6 +3,9 @@
 .vimsession
 .*.sw[a-z]
 
+# Ignore auto-generated files
+proplotrc
+
 # PyPi stuff
 build
 dist

CHANGELOG.rst

@@ -38,11 +38,42 @@ ProPlot v0.5.0 (2020-##-##)
   stacks rather than getting inserted directly into
   the main `~proplot.subplots.GridSpec` (:pr:`50`).
 
+ProPlot v0.4.1 (2020-01-08)
+===========================
+.. rubric:: Deprecation
+
+- Change the default ``.proplotrc`` format from YAML to the ``.matplotlibrc``
+  syntax (:pr:`101`).
+
+.. rubric:: Features
+
+- Comments (lines starting with ``#``) are now permitted in all RGB and HEX style
+  colormap and cycle files (:pr:`100`).
+- Break down `~proplot.styletools.show_cycles` bars into categories, just
+  like `~proplot.styletools.show_cmaps` (:pr:`100`).
+
+.. rubric:: Bug fixes
+
+- Fix issue where `~proplot.styletools.show_cmaps` and `~proplot.styletools.show_cycles`
+  draw empty axes (:pr:`100`).
+- Add back the :ref:`default .proplorc file <The .proplotrc file>` to docs (:pr:`101`).
+  To do this, ``conf.py`` auto-generates a file in ``_static``.
+
+.. rubric:: Internals
+
+- Add ``geogrid.color/linewidth/etc`` and ``gridminor.color/linewidth/etc`` props
+  as *children* of ``grid.color/linewidth/etc`` (:pr:`101`).
+- Various `~proplot.rctools.rc_configurator` improvements, remove outdated
+  global variables (:pr:`101`).
+- Better error handling when loading colormap/cycle files, and calls to
+  `~proplot.styletools.Colormap` and `~proplot.styletools.Cycle` now raise errors while
+  calls to `~proplot.styletools.register_cmaps` and `~proplot.styletools.register_cycles`
+  still issue warnings (:pr:`100`).
+
 ProPlot v0.4.0 (2020-01-07)
 ===========================
 .. rubric:: Deprecated
 
-
 - Rename `basemap_defaults` to `~proplot.projs.basemap_kwargs` and `cartopy_projs`
   to `~proplot.projs.cartopy_names` (:commit:`431a06ce`).
 - Remove ``subplots.innerspace``, ``subplots.titlespace``,

docs/conf.py

@@ -13,10 +13,11 @@
 
 import os
 import sys
+from proplot.rctools import _write_defaults
 from pygments.formatters import HtmlFormatter
 from pygments.styles import get_all_styles
 
-# Sphinx-automodapi requires proplot on path
+# Add proplot to path for sphinx-automodapi
 sys.path.insert(0, os.path.abspath('..'))
 
 # Add docs folder to PATH for local 'sphinxext' extensions
@@ -194,6 +195,9 @@
     with open(path, 'w') as f:
         f.write(HtmlFormatter(style=style).get_style_defs('.highlight'))
 
+# Create sample .proplotrc file
+_write_defaults(os.path.join('_static', 'proplotrc'), comment=False)
+
 # Role
 # default family is py, but can also set default role so don't need
 # :func:`name`, :module:`name`, etc.

docs/configuration.rst

@@ -7,23 +7,23 @@ Overview
 A special object named `~proplot.rctools.rc`, belonging to the
 `~proplot.rctools.rc_configurator` class, is created on import.
 This is your one-stop shop for changing global settings belonging to any of
-the following three categories.
+the following three categories:
 
 1. Builtin matplotlib `rcParams <https://matplotlib.org/users/customizing.html>`__
    settings. These have the format ``x.y`` or ``x.y.z``.
 2. ProPlot :ref:`rcParamsLong` settings. These also have the format ``x.y``
    (see below).
 3. ProPlot :ref:`rcParamsShort` settings. These have no dots (see below).
 
-You can change settings with the `~proplot.rctools.rc` object as follows.
+You can change settings with the `~proplot.rctools.rc` object as follows:
 
 * ``plot.rc.name = value``
 * ``plot.rc['name'] = value``
 * ``plot.rc.update(name1=value1, name2=value2)``
 * ``plot.rc.update({'name1':value1, 'name2':value2})``
 
 To temporarily change settings on a particular axes, use either of the
-following.
+following:
 
 * ``ax.format(name=value)``
 * ``ax.format(rc_kw={'name':value})``
@@ -102,8 +102,8 @@ There are two new additions to the ``image`` category, and the new
 `~proplot.axes.Axes.colorbar` properties.
 The new ``gridminor`` category controls minor gridline settings,
 and the new ``geogrid`` category controls meridian and parallel line settings
-for `~proplot.axes.ProjAxes`. For both ``gridminor`` and ``geogrid``, if
-a property is empty, the corresponding property from ``grid`` is used.
+for `~proplot.axes.ProjAxes`. Note that when a ``grid`` property is changed,
+it also changed the corresponding ``gridminor`` property.
 
 Finally, the ``geoaxes``, ``land``, ``ocean``, ``rivers``, ``lakes``,
 ``borders``, and ``innerborders`` categories control various
@@ -195,11 +195,9 @@ To modify the global settings, edit your
 ``~/.proplotrc`` file. To modify settings for a particular project,
 create a ``.proplotrc`` file in the same directory as your ipython
 notebook, or in an arbitrary parent directory.
+As an example, a ``.proplotrc`` file containing the default settings
+is shown below. The syntax is mostly the same as the syntax used for
+`matplotlibrc files <https://matplotlib.org/3.1.1/tutorials/introductory/customizing.html#customizing-with-matplotlibrc-files>`__.
 
-As an example, the default ``.proplotrc`` file
-is shown below. The syntax is roughly the same as that used for
-``matplotlibrc`` files, although ``.proplotrc`` strictly adheres to
-`YAML <https://en.wikipedia.org/wiki/YAML>`__.
-
-.. include:: ../proplot/.proplotrc
+.. include:: _static/proplotrc
    :literal:

docs/environment.yml

@@ -18,7 +18,6 @@ dependencies:
   - pip
   - pip:
     - ..
-    - pyyaml
     - pyqt5
     - nbsphinx
     - sphinx_rtd_theme

proplot/axes.py

@@ -17,7 +17,7 @@
 import matplotlib.collections as mcollections
 from . import projs, axistools
 from .utils import _warn_proplot, _notNone, units, arange, edges
-from .rctools import rc, RC_NODOTSNAMES
+from .rctools import rc, _rc_nodots
 from .wrappers import (
     _get_transform, _norecurse, _redirect,
     _add_errorbars, _bar_wrapper, _barh_wrapper, _boxplot_wrapper,
@@ -107,7 +107,7 @@ def _parse_format(mode=2, rc_kw=None, **kwargs):
     kw = {}
     rc_kw = rc_kw or {}
     for key, value in kwargs.items():
-        key_fixed = RC_NODOTSNAMES.get(key, None)
+        key_fixed = _rc_nodots.get(key, None)
         if key_fixed is None:
             kw[key] = value
         else:
@@ -1691,7 +1691,7 @@ def _parse_alt(x, kwargs):
                 f'Twin axis keyword arg {key!r} is deprecated. '
                 f'Use {key[1:]!r} instead.')
             kw_out[key] = value
-        elif key in RC_NODOTSNAMES:
+        elif key in _rc_nodots:
             kw_out[key] = value
         else:
             kw_bad[key] = value
@@ -2383,14 +2383,9 @@ def _grid_dict(grid):
                     if which == 'major':
                         kw_grid = rc.fill(_grid_dict('grid'), context=True)
                     else:
-                        kw_major = kw_grid
                         kw_grid = rc.fill(
                             _grid_dict('gridminor'), context=True
                         )
-                        kw_grid.update({
-                            key: value for key, value in kw_major.items()
-                            if key not in kw_grid
-                        })
                     # Changed rc settings
                     if gridcolor is not None:
                         kw['grid_color'] = gridcolor

proplot/axistools.py

@@ -141,7 +141,7 @@ def Locator(locator, *args, **kwargs):
 
 
 def Formatter(formatter, *args, date=False, index=False, **kwargs):
-    r"""
+    """
     Return a `~matplotlib.ticker.Formatter` instance. This function is used to
     interpret the `xformatter`, `xformatter_kw`, `yformatter`, and
     `yformatter_kw` arguments when passed to
@@ -1092,12 +1092,12 @@ def transform_non_affine(self, a):
 
 
 class MercatorLatitudeScale(_ScaleBase, mscale.ScaleBase):
-    r"""
+    """
     Axis scale that transforms coordinates as with latitude in the `Mercator \
 projection <http://en.wikipedia.org/wiki/Mercator_projection>`__.
     Adapted from `this matplotlib example \
 <https://matplotlib.org/examples/api/custom_scale_example.html>`__.
-    The scale function is as follows:
+    """r""""The scale function is as follows:
 
     .. math::