Break things up into smaller files, improve docs, various bugfixes#149
Merged
Conversation
This was referenced May 9, 2020
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This really does too many things for just one PR, but I was kind of "in the zone" making these edits and only tried to break them up into smaller commits after the fact. This is the kind of enormous refactor PR that will become rarer once the project matures and the v1.0.0 milestone is reached and the project can become more community-driven.
The biggest change: this PR moves everything around into smaller files with more sensible grouping and more intuitive filenames, mimicking the matplotlib file structure, and adds an
internalsfolder with internal utilities (e.g. tools for generating deprecation warnings)This also stops syncing ipython notebooks directly and uses jupytext
py:percentfiles instead, and makes some major documentation improvements.Because I started to do additional work on top of the moved files, this PR also contains bugfixes and a couple feature additions that would otherwise have their own PRs. But I did manage to isolate these changes into meaningful commits, which are individually referenced in the CHANGELOG.rst.
This PR renames some classes and utility functions that users rarely interact with, but had not-very-sensible names (the old versions are still there, but a deprecation warning is issued when the function is called/class is instantiated). So far this consists of:
shade()-->scale_luminance()("shade" has ambiguous meaning)saturate()-->scale_saturation()(match the convention forscale_luminance)GeoAxes()-->CartopyAxes()ProjAxes()-->GeoAxes()(more obvious name as "base class" for the geographic axes classes specific to each package,CartopyAxesandBasemapAxes, and if/when basemap support is deprecated it will be easy to just get rid of the subclasses and simply move theCartopyAxesfeatures ontoGeoAxes)BinNorm()-->DiscreteNorm()(the fact that its normalized output colors are non-continuous is its defining feature)subplot_grid()-->SubplotsContainer()(match convention for class names)inline_backend_fmt()-->config_inline_backend()(because it runs magic%config InlineBackendand does more than changing figure formats)Colormap.concatenate()-->Colormap.append()(because "concatenate" implies a static method or separate function that concatenates input colormaps)Colormap.truncated()-->Colormap.truncate()(prefer imperative tense)Colormap.punched()-->Colormap.cut()(prefer imperative tense, much better name)Colormap.updated()-->Colormap.copy()(prefer imperative tense)ColorDict()-->ColorDatabase()CmapDict()-->ColormapDatabase()Finally, this removes the public attributes
cmaps,cycles,colordict,locators,formatters,basemap_kwargs,cartopy_crs. Since these were just meant as a sort of documentation feature for users to check out registered names on-the-fly (had no intended/advertised practical functionality), they are removed without deprecation. It makes more sense for users to look at online documentation, the docstrings, or just try to retrieve a non-existing class with a constructor function (e.g.Formatter('foo')) and read the error message, which lists all the registered names.