Sort imports and cleanup pre-commit, CI workflow

Author: lukelbd

.pre-commit-config.yaml

@@ -1,5 +1,6 @@
 # See: https://pre-commit.com/hooks.html
 # Must put flake8 in separate group so 'black' is executed first
+# WARNING: Make sure to keep flags in sync with ci/run-linter.sh
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v3.1.0
@@ -11,6 +12,7 @@ repos:
     - id: end-of-file-fixer
     - id: trailing-whitespace
 
+  # apply after format() kwargs broken up into setters
   # - repo: https://github.com/ambv/black
   #   rev: 19.10
   #   hooks:
@@ -21,16 +23,17 @@ repos:
     rev: v4.3.21
     hooks:
     - id: isort
-      args: ['--line-width', '88']
+      args: ['--line-width=88', '--multi-line=3', '--force-grid-wrap=0', '--trailing-comma']
 
   - repo: https://github.com/PyCQA/flake8
     rev: 3.8.3
     hooks:
     - id: flake8
       args: ['--max-line-length=88', '--ignore=W503,E402,E741']
 
-  - repo: https://github.com/PyCQA/doc8
-    rev: 0.8.1
-    hooks:
-    - id: doc8
-      args: ['--max-line-length', '88', '--allow-long-titles']
+  # apply once this handles long tables better
+  # - repo: https://github.com/PyCQA/doc8
+  #   rev: 0.8.1
+  #   hooks:
+  #   - id: doc8
+  #     args: ['--max-line-length', '88', '--allow-long-titles']

INSTALL.rst

@@ -1,7 +1,9 @@
 Installation
 ============
 
-ProPlot is published on `PyPi <https://pypi.org/project/proplot/>`__ and `conda-forge <https://conda-forge.org>`__. It can be installed with ``pip`` or ``conda`` as follows:
+ProPlot is published on `PyPi <https://pypi.org/project/proplot/>`__
+and `conda-forge <https://conda-forge.org>`__. It can be installed
+with ``pip`` or ``conda`` as follows:
 
 .. code-block:: bash
 
@@ -16,6 +18,13 @@ Likewise, an existing installation of ProPlot can be upgraded to the latest vers
    conda upgrade proplot
 
 
-To install a development version of ProPlot, you can use ``pip install git+https://github.com/lukelbd/proplot.git`` or clone the repository and run ``pip install -e .`` inside the ``proplot`` folder.
+To install a development version of ProPlot, you can use
+``pip install git+https://github.com/lukelbd/proplot.git``
+or clone the repository and run ``pip install -e .`` inside
+the ``proplot`` folder.
 
-ProPlot's only hard dependency is `matplotlib <https://matplotlib.org/>`__. The *soft* dependencies are `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__, `basemap <https://matplotlib.org/basemap/index.html>`__, `xarray <http://xarray.pydata.org>`__, and `pandas <https://pandas.pydata.org>`__. See the documentation for details.
+ProPlot's only hard dependency is `matplotlib <https://matplotlib.org/>`__.
+The *soft* dependencies are `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__,
+`basemap <https://matplotlib.org/basemap/index.html>`__,
+`xarray <http://xarray.pydata.org>`__, and `pandas <https://pandas.pydata.org>`__.
+See the documentation for details.

README.rst

@@ -18,14 +18,18 @@ ProPlot is published on `PyPi <https://pypi.org/project/proplot/>`__ and
    pip install proplot
    conda install -c conda-forge proplot
 
-Likewise, an existing installation of ProPlot can be upgraded to the latest version with:
+Likewise, an existing installation of ProPlot can be upgraded
+to the latest version with:
 
 .. code-block:: bash
 
    pip install --upgrade proplot
    conda upgrade proplot
 
-To install a development version of ProPlot, you can use ``pip install git+https://github.com/lukelbd/proplot.git`` or clone the repository and run ``pip install -e .`` inside the ``proplot`` folder.
+To install a development version of ProPlot, you can use
+``pip install git+https://github.com/lukelbd/proplot.git``
+or clone the repository and run ``pip install -e .``
+inside the ``proplot`` folder.
 
 Documentation
 =============

ci/run-linter.sh

@@ -1,20 +1,21 @@
 #!/bin/bash
+# Run the travis CI tests
+# WARNING: Make sure to keep flags in sync with .pre-commit.config.yaml
 set -e
 set -eo pipefail
 
 echo 'Code Styling with (flake8, isort)'
 
-source activate proplot-dev
-
 echo '[flake8]'
-flake8 proplot docs --max-line-length=88 --ignore=W503,E402,E741
+flake8 proplot docs --exclude .ipynb_checkpoints --max-line-length=88 --ignore=W503,E402,E741
 
-# TODO: Add this
+# Apply after format() kwargs broken up into setters
 # echo '[black]'
 # black --check -S proplot
 
 echo '[isort]'
-isort --recursive --check-only --line-width=88 proplot
+isort --recursive --check-only --line-width=88 --multi-line=3 --force-grid-wrap=0 --trailing-comma proplot
 
-echo '[doc8]'
-doc8 *.rst docs --max-line-length=88
+# Apply once this handles long tables better
+# echo '[doc8]'
+# doc8 *.rst docs/*.rst --max-line-length=88

docs/faq.rst

@@ -5,51 +5,107 @@ Frequently asked questions
 What makes this matplotlib wrapper different?
 =============================================
 
-There is already a great matplotlib wrapper called `seaborn <https://seaborn.pydata.org/>`__. Also, `pandas <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.plot.html>`__ and `xarray <http://xarray.pydata.org/en/stable/plotting.html>`__ both offer convenient matplotlib plotting commands. How does ProPlot compare against these tools?
-
-* ProPlot, seaborn, pandas, and xarray all offer tools for generating rigid, simple, nice-looking plots from data stored in `~pandas.DataFrame`\ s and `~xarray.DataArray`\ s (ProPlot tries to apply labels from these objects, just like pandas and xarray).
-* Unlike seaborn, pandas, and xarray, ProPlot *also* works for arbitrarily complex subplot grids, and ProPlot provides tools for heavily customizing plots.
-* ProPlot is integrated with *cartopy* and *basemap*. You will find plotting geophysical data in ProPlot to be much more concise than working with cartopy and basemap directly.
-* ProPlot *expands upon* the seaborn tools for working with color and global settings. For example, see `~proplot.constructor.Colormap`, `~proplot.colors.PerceptuallyUniformColormap`, and `~proplot.config.RcConfigurator`.
-* ProPlot *expands upon* matplotlib by fixing various quirks, developing a more sophisticated automatic layout algorithm, simplifying the process of drawing outer colorbars and legends, and much more.
-* ProPlot is *built right into the matplotlib API*, thanks to special subclasses of the `~matplotlib.figure.Figure` and `~matplotlib.axes.Axes` classes, while seaborn, pandas, and xarray are meant to be used separately from the matplotlib API.
-
-In a nutshell, ProPlot is intended to *unify the convenience of seaborn, pandas, and xarray plotting with the power and customizability of the underlying matplotlib API*.
+There is already a great matplotlib wrapper called
+`seaborn <https://seaborn.pydata.org/>`__. Also, `pandas\
+<https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.plot.html>`__
+and `xarray <http://xarray.pydata.org/en/stable/plotting.html>`__
+both offer convenient matplotlib plotting commands.
+How does ProPlot compare against these tools?
+
+* ProPlot, seaborn, pandas, and xarray all offer tools for generating rigid, simple,
+  nice-looking plots from data stored in `~pandas.DataFrame`\ s and
+  `~xarray.DataArray`\ s (ProPlot tries to apply labels from these objects, just like
+  pandas and xarray).
+* Unlike seaborn, pandas, and xarray, ProPlot *also* works for arbitrarily complex
+  subplot grids, and ProPlot provides tools for heavily customizing plots.
+* ProPlot is integrated with *cartopy* and *basemap*. You will find plotting geophysical
+  data in ProPlot to be much more concise than working with cartopy and basemap
+  directly.
+* ProPlot *expands upon* the seaborn tools for working with color and global settings.
+  For example, see `~proplot.constructor.Colormap`,
+  `~proplot.colors.PerceptuallyUniformColormap`, and `~proplot.config.RcConfigurator`.
+* ProPlot *expands upon* matplotlib by fixing various quirks, developing a more
+  sophisticated automatic layout algorithm, simplifying the process of drawing outer
+  colorbars and legends, and much more.
+* ProPlot is *built right into the matplotlib API*, thanks to special subclasses of the
+  `~matplotlib.figure.Figure` and `~matplotlib.axes.Axes` classes, while seaborn,
+  pandas, and xarray are meant to be used separately from the matplotlib API.
+
+In a nutshell, ProPlot is intended to *unify the convenience of seaborn, pandas, and
+xarray plotting with the power and customizability of the underlying matplotlib API*.
 
 ..
   So while ProPlot includes similar tools, the scope and goals are largely different.
-  Indeed, parts of ProPlot were inspired by these projects -- in particular, ``setup.py`` and ``colortools.py`` are modeled after seaborn. However the goals and scope of ProPlot are largely different:
+  Indeed, parts of ProPlot were inspired by these projects -- in particular,
+  ``setup.py`` and ``colortools.py`` are modeled after seaborn. However the goals and
+  scope of ProPlot are largely different:
 
 Why didn't you add to matplotlib directly?
 ==========================================
 
-Since ProPlot is built right into the matplotlib API, you might be wondering why we didn't contribute to the matplotlib project directly.
-
-* Certain features directly conflict with matplotlib. For example, ProPlot's tight layout algorithm conflicts with matplotlib's `tight layout <https://matplotlib.org/tutorials/intermediate/tight_layout_guide.html>`__ by permitting *fluid figure dimensions*, and the new `~proplot.gridspec.GridSpec` class permits *variable spacing* between rows and columns and uses *physical units* rather than figure-relative and axes-relative units.
-* Certain features are arguably too redundant. For example, `~proplot.axes.Axes.format` is convenient, but the same tasks can be accomplished with existing axes and axis "setter" methods. Also, some of the functionality of `~proplot.ui.subplots` can be replicated with `axes_grid1 <https://matplotlib.org/mpl_toolkits/axes_grid1/index.html>`__. Following `TOOWTDI <https://wiki.python.org/moin/TOOWTDI>`__ philosophy, these features should probably not be integrated.
+Since ProPlot is built right into the matplotlib API, you might be wondering why we
+didn't contribute to the matplotlib project directly.
+
+* Certain features directly conflict with matplotlib. For example, ProPlot's tight
+  layout algorithm conflicts with matplotlib's `tight layout\
+  <https://matplotlib.org/tutorials/intermediate/tight_layout_guide.html>`__ by
+  permitting *fluid figure dimensions*, and the new `~proplot.gridspec.GridSpec` class
+  permits *variable spacing* between rows and columns and uses *physical units* rather
+  than figure-relative and axes-relative units.
+* Certain features are arguably too redundant. For example, `~proplot.axes.Axes.format`
+  is convenient, but the same tasks can be accomplished with existing axes and axis
+  "setter" methods. Also, some of the functionality of `~proplot.ui.subplots` can be
+  replicated with `axes_grid1\
+  <https://matplotlib.org/mpl_toolkits/axes_grid1/index.html>`__. Following `TOOWTDI
+  <https://wiki.python.org/moin/TOOWTDI>`__ philosophy, these features should probably
+  not be integrated.
 
 ..
-   * ProPlot design choices are made with the academic scientist working with ipython notebooks in mind, while matplotlib has a much more diverse base of hundreds of thousands of users. Matplotlib developers have to focus on support and API consistency, while ProPlot can make more dramatic improvements.
+   * ProPlot design choices are made with the academic scientist working with ipython
+     notebooks in mind, while matplotlib has a much more diverse base of hundreds of
+     thousands of users. Matplotlib developers have to focus on support and API
+     consistency, while ProPlot can make more dramatic improvements.
 
-Nevertheless, if any core matplotlib developers think that some of ProPlot's features should be added to matplotlib, please contact `Luke Davis <https://github.com/lukelbd>`__ and let him know!
+Nevertheless, if any core matplotlib developers think that some of ProPlot's features
+should be added to matplotlib, please contact
+`Luke Davis <https://github.com/lukelbd>`__ and let him know!
 
 Why do my inline figures look different?
 ========================================
 
-These days, most publications prefer plots saved as `vector graphics <https://en.wikipedia.org/wiki/Vector_graphics>`__ [1]_ rather than `raster graphics <https://en.wikipedia.org/wiki/Raster_graphics>`__ [2]_. When you save vector graphics, the content sizes should be appropriate for embedding the plot in a document (for example, if an academic journal recommends 8-point font for plots, you should use 8-point font in your plotting code).
-
-Most of the default matplotlib backends make low-quality, artifact-plagued jpegs. To keep them legible, matplotlib uses a fairly large default figure width of 6.5 inches (usually only suitable for multi-panel plots) and a slightly large default font size of 10 points (where most journals recommend 5-9 points). This means your figures have to be downscaled so the sizes used in your plotting code are *not* the sizes that appear in the document.
+These days, most publications prefer plots saved as
+`vector graphics <https://en.wikipedia.org/wiki/Vector_graphics>`__ [1]_
+rather than `raster graphics <https://en.wikipedia.org/wiki/Raster_graphics>`__ [2]_.
+When you save vector graphics, the content sizes should be appropriate for embedding the
+plot in a document (for example, if an academic journal recommends 8-point font for
+plots, you should use 8-point font in your plotting code).
+
+Most of the default matplotlib backends make low-quality, artifact-plagued jpegs. To
+keep them legible, matplotlib uses a fairly large default figure width of 6.5 inches
+(usually only suitable for multi-panel plots) and a slightly large default font size of
+10 points (where most journals recommend 5-9 points). This means your figures have to be
+downscaled so the sizes used in your plotting code are *not* the sizes that appear in
+the document.
+
+ProPlot helps you get your figure sizes *correct* for embedding them as vector graphics
+inside publications.  It uses a slightly smaller default font size, calculates the
+default figure size from the number of subplot rows and columns, and adds the `journal`
+keyword argument to `~proplot.figure.Figure` which can be used to employ figure
+dimensions from a particular journal standard.  To keep the inline figures legible,
+ProPlot also employs a *higher quality* default inline backend.
+
+.. [1] `Vector graphics <https://en.wikipedia.org/wiki/Vector_graphics>`__ use physical
+   units (e.g. inches, `points <https://en.wikipedia.org/wiki/Point_(typography)>`__),
+   are infinitely scalable, and often have much smaller file sizes than bitmap graphics.
+   You should consider using them even when your plots are not destined for publication.
+   PDF, SVG, and EPS are the most common formats.
+
+.. [2] `Raster graphics <https://en.wikipedia.org/wiki/Raster_graphics>`__ use pixels
+   and are *not* infinitely scalable. They tend to be faster to display and easier
+   to view, but they are discouraged by most academic publishers. PNG and JPG are the
+   most common formats.
 
-ProPlot helps you get your figure sizes *correct* for embedding
-them as vector graphics inside publications.
-It uses a slightly smaller default font size, calculates the default figure
-size from the number of subplot rows and columns, and
-adds the `journal` keyword argument to `~proplot.figure.Figure` which can
-be used to employ figure dimensions from a particular journal standard.
-To keep the inline figures legible, ProPlot also employs a *higher quality* default
-inline backend.
-
-.. [1] `Vector graphics <https://en.wikipedia.org/wiki/Vector_graphics>`__ use physical units (e.g. inches, `points <https://en.wikipedia.org/wiki/Point_(typography)>`__), are infinitely scalable, and often have much smaller file sizes than bitmap graphics.  You should consider using them even when your plots are not destined for publication. PDF, SVG, and EPS are the most common formats.
-.. [2] `Raster graphics <https://en.wikipedia.org/wiki/Raster_graphics>`__ use pixels and are *not* infinitely scalable. They tend to be faster to display and easier to view, but they are discouraged by most academic publishers. PNG and JPG are the most common formats.
-
-.. users to enlarge their figure dimensions and font sizes so that content inside of the inline figure is visible -- but when saving the figures for publication, it generally has to be shrunk back down!
+..
+   users to enlarge their figure dimensions and font sizes so that content inside of the
+   inline figure is visible -- but when saving the figures for publication, it generally
+   has to be shrunk back down!