Skip to content

Clean up and clarify Normalize docs #16271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Jan 22, 2020
Merged

Clean up and clarify Normalize docs #16271

merged 1 commit into from
Jan 22, 2020

Conversation

dstansby
Copy link
Member

@dstansby dstansby commented Jan 20, 2020 •
edited
Loading

I'm trying to debug SymLogNorm, so thought I'd start by tidying up the Normalize docs to make them clearer. Suggestions very welcome.

anntzer
anntzer reviewed Jan 20, 2020
View reviewed changes
anntzer
anntzer reviewed Jan 20, 2020
View reviewed changes
anntzer
anntzer reviewed Jan 20, 2020
View reviewed changes
@anntzer
Copy link
Contributor

anntzer commented Jan 20, 2020

I agree with splitting an "abstract" normbase from the linear norm.

anntzer
anntzer reviewed Jan 21, 2020
View reviewed changes
lib/matplotlib/colors.py Outdated

Parameters
----------
value :
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no colon

@timhoffm
Copy link
Member

timhoffm commented Jan 21, 2020 •
edited
Loading

The naming Normalize has been annoying me for a while. It breaks with every other norm naming, which is XxxNorm and it's really imprcise. I would be very much in favor of soft-deprecating it in favor of LinearNorm. `Normalize can stay for back-compatibility, but not actively using it in modern code would increase readability and consistency quite a bit.

I agree on adding an abstract norm class. Not a fan of naming it NormBase. I recognize that we've named all base classes XxxBase, which feels not quite right - neither the word order nor using Base at all. Even though it would be moving away from an estrablished pattern, could we use AbstractNorm?

@dstansby
Copy link
Member Author

dstansby commented Jan 21, 2020 •
edited
Loading

👍 sounds good, I'll take a go at that in this PR. How about just Norm? Maybe too simple, I do like AbstractNorm but for some reason doing isinstance(obj, AbstractNorm) seems odd to me.

@anntzer
Copy link
Contributor

anntzer commented Jan 21, 2020

I guess BaseNorm would be somewhat more idiomatic but just weird given all the XxxBase we have. I think the problem of AbstractNorm is that it's also what you'd use in all docstrings which currently read norm : Normalize; norm : AbstractNorm is just weird whereas norm : BaseNorm or norm : NormBase seem OK?

@dstansby dstansby force-pushed the norm-doc branch 2 times, most recently from a70383f to 7037ec1 Compare January 22, 2020 10:51
@dstansby
Copy link
Member Author

I'm going to leave this PR as just doc changes, and put the other stuff elswehere since it's turning out to be a bit of a big diff.

anntzer
anntzer approved these changes Jan 22, 2020
View reviewed changes
Copy link
Contributor

@anntzer anntzer left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

once ci passes (modulo the scipy failure)

@anntzer
Copy link
Contributor

anntzer commented Jan 22, 2020

failure is the scipy one.

@anntzer anntzer merged commit 47cfa35 into matplotlib:master Jan 22, 2020
@anntzer anntzer mentioned this pull request Jan 22, 2020
Merged
6 tasks
@QuLogic QuLogic added this to the v3.3.0 milestone Feb 12, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@anntzer anntzer anntzer approved these changes

Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.3.0
Development

Successfully merging this pull request may close these issues.
4 participants
@dstansby @anntzer @timhoffm @QuLogic