FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

DOC: rename Usage Guide to Basic Usage and update by jklymak · Pull Request #21641 · matplotlib/matplotlib · GitHub

  1. matplotlib
  2. matplotlib

Repository navigation

DOC: rename Usage Guide to Basic Usage and update - #21641

Merged
tacaswell merged 1 commit into
matplotlib:mainfrom
jklymak:doc-basic-usage
Nov 27, 2021
ConversationCommits (1)ChecksFiles changed
Merged

DOC: rename Usage Guide to Basic Usage and update#21641
tacaswell merged 1 commit into
matplotlib:mainfrom
jklymak:doc-basic-usage

Conversation

jklymak commented Nov 15, 2021 •
edited
Loading

Copy link
Copy Markdown
Member

PR Summary

Renames Usage Guide tutorial to Basic Usage (tutorials/introductory/usage.py). This adds extensively to this guide to provide a short overview of how to use Matplotlib, with links to other tutorials or examples where appropriate or necessary. This is meant to be on par with the pyplot tutorial, but doesn't follow it slavishly.

History

This page used to have a bunch of explanatory material. A lot of this was moved in #21335 to /docs/users leaving this page quite thin. There is already the pyplot tutorial, and the "lifecycle of a plot" tutorial, but the pyplot tutorial is not the style we'd prefer people to use, and "lifecycle" goes deep in a couple of directions. (Actually, I'd like to remove that tutorial as well, or make it more "scientific" by not just making a bar plot of all things, but that is lower priority)

Goal

Not completeness, but enough ideas of what the library can do to point users to more complete resources.

Use default styles wherever possible. Only exception are the figure sizes, which are usually unsuitable for a website tutorial (in my opinion).

If there is a major part of the library for basic usage, feel free to comment.

Outline:

Basic usage

  • plot
  • anatomy
  • Note on coding styles
  • styling artists
    • colors
    • linestyles
    • markerstyles
  • labelling plots
    • xlabel, ylabel and title
    • axis: ticks and ticklabels (locators and formatters)
      • units: categorical and dates
    • text
    • annotations
    • legends
  • colormapping data
    • basic and colormaps
    • vmin, vmax
    • norms
    • colorbars
  • arranging axes
    • subplots
    • subplot_mosaic

[NOTE: depends on #21631 - I'll rebase when that is done. Only file to change is tutorials/introductory/usage.py]

PR Checklist

Tests and Styling

  • Has pytest style unit tests (and pytest passes).
  • Is Flake 8 compliant (install flake8-docstrings and run flake8 --docstring-convention=all).

Documentation

  • New features are documented, with examples if plot related.
  • New features have an entry in doc/users/next_whats_new/ (follow instructions in README.rst there).
  • API changes documented in doc/api/next_api_changes/ (follow instructions in README.rst there).
  • Documentation is sphinx and numpydoc compliant (the docs should build without error).

jklymak added the Documentation: website layout/behavior/styling changes label Nov 15, 2021
jklymak force-pushed the doc-basic-usage branch 3 times, most recently from 0b339f7 to 85de443 Compare November 15, 2021 15:15
jklymak marked this pull request as draft November 15, 2021 15:18
jklymak changed the title DOC: rename Usage Guide to Basic Usage... DOC: rename Usage Guide to Basic Usage and update Nov 16, 2021
jklymak marked this pull request as ready for review November 16, 2021 12:56
jklymak added this to the v3.5-doc milestone Nov 17, 2021

jklymak commented Nov 25, 2021

Copy link
Copy Markdown
Member Author

rebased on main...

tacaswell reviewed Nov 25, 2021
View reviewed changes
Comment thread tutorials/introductory/usage.py
tacaswell reviewed Nov 25, 2021
View reviewed changes
Comment thread tutorials/introductory/usage.py
tacaswell reviewed Nov 25, 2021
View reviewed changes
Comment thread tutorials/introductory/usage.py
def my_plotter(ax, data1, data2, param_dict):
"""
A helper function to make a graph
A helper function to make a graph.

tacaswell Nov 25, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I have mixed feeling about dropping the docstring. On one hand, I see the reason to make it terser, on the other hand we should model best practices.

jklymak Nov 26, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I don't feel strongly about this, and am happy to add it back in. However, I think for a little in-script utility its OK to not have a numpydoc compliant docstring, and I found it distracting for a tutorial.

tacaswell reviewed Nov 26, 2021
View reviewed changes
Comment thread tutorials/introductory/usage.py Outdated
Comment on lines +294 to +297
ax.set_xlabel('Smarts')
ax.set_ylabel('Probability')
ax.set_title('Histogram of IQ')
ax.text(60, .025, r'$\mu=100,\ \sigma=15$')

tacaswell Nov 26, 2021 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality
Suggested change
ax.set_xlabel('Smarts')
ax.set_ylabel('Probability')
ax.set_title('Histogram of IQ')
ax.text(60, .025, r'$\mu=100,\ \sigma=15$')
ax.set_xlabel('Value')
ax.set_ylabel('Probability')
ax.set_title('Histogram of normal distribution')
ax.text(60, .025, r'$\mu=100,\ \sigma=15$')

jklymak Nov 26, 2021

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Changed to aardvark length (with a caveat that the distribution was not real, though I changed the mean to be correct for aardvarks).

tacaswell approved these changes Nov 26, 2021
View reviewed changes

tacaswell left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

I think this a big improvement.

I left one additional comment changing the text in an example (IQ can be controversial and is non-material to the point we are trying to make so might as well avoid courting controversy), but won't block merging over that.

@jklymak can self-merge either taking the suggestion or not.

jklymak commented Nov 26, 2021 •
edited
Loading

Copy link
Copy Markdown
Member Author

Yeah that one was left over from before so I didn't change it. But I wondered about it as well and am happy to switch to aardvark length or something.

We actually have a gender one somewhere which strikes me as even more potentially contentious - i will try and remember to open an issue for that

tacaswell merged commit edd5a70 into matplotlib:main Nov 27, 2021

lumberbot-app Bot commented Nov 27, 2021

Copy link
Copy Markdown

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

  1. Checkout backport branch and update it.
git checkout v3.5.x
git pull
  1. Cherry pick the first parent branch of the this PR on top of the older branch:
git cherry-pick -m1 edd5a70b0a9ef03f7146268e8e9f52ab32e83d0d
  1. You will likely have some merge/cherry-pick conflict here, fix them and commit:
git commit -am 'Backport PR #21641: DOC: rename Usage Guide to Basic Usage and update'
  1. Push to a named branch:
git push YOURFORK v3.5.x:auto-backport-of-pr-21641-on-v3.5.x
  1. Create a PR against branch v3.5.x, I would have named this PR:

"Backport PR #21641 on branch v3.5.x (DOC: rename Usage Guide to Basic Usage and update)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

lumberbot-app Bot commented Nov 27, 2021

Copy link
Copy Markdown

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

  1. Checkout backport branch and update it.
git checkout v3.5.0-doc
git pull
  1. Cherry pick the first parent branch of the this PR on top of the older branch:
git cherry-pick -m1 edd5a70b0a9ef03f7146268e8e9f52ab32e83d0d
  1. You will likely have some merge/cherry-pick conflict here, fix them and commit:
git commit -am 'Backport PR #21641: DOC: rename Usage Guide to Basic Usage and update'
  1. Push to a named branch:
git push YOURFORK v3.5.0-doc:auto-backport-of-pr-21641-on-v3.5.0-doc
  1. Create a PR against branch v3.5.0-doc, I would have named this PR:

"Backport PR #21641 on branch v3.5.0-doc (DOC: rename Usage Guide to Basic Usage and update)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

jklymak deleted the doc-basic-usage branch November 27, 2021 07:44
jklymak mentioned this pull request Nov 29, 2021
Merged
6 tasks
jklymak pushed a commit to jklymak/matplotlib that referenced this pull request Nov 30, 2021
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
22d8384 
DOC: rename Usage Guide to Basic Usage and update
jklymak pushed a commit to jklymak/matplotlib that referenced this pull request Nov 30, 2021
Backport PR matplotlib#21641: DOC: rename Usage Guide to Basic Usage …
a8f2157 
…and update
jklymak added a commit that referenced this pull request Nov 30, 2021
Merge pull request #21812 from jklymak/auto-backport-of-pr-21641-on-v…
dd2c621 
…3.5.x

Backport #21641
jklymak added a commit that referenced this pull request Nov 30, 2021
Merge pull request #21813 from jklymak/auto-backport-of-pr-21641-on-v…
98a383f 
…3.5.0-doc

Backport PR #21641: DOC: rename Usage Guide to Basic Usage and update
story645 mentioned this pull request Nov 17, 2022
Open
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
a34173e 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
baf7259 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
5e51afb 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
36ff190 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
82b194b 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
4a3cae0 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
09ce52e 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
d393bcf 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
a56ad85 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
a125dda 
DOC: rename Usage Guide to Basic Usage and update
imgbot Bot pushed a commit to kkipngenokoech/matplotlib that referenced this pull request Apr 19, 2026
Merge pull request matplotlib#21641 from jklymak/doc-basic-usage
6723559 
DOC: rename Usage Guide to Basic Usage and update
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
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

tacaswell tacaswell approved these changes

Assignees

No one assigned

Labels

Documentation: website layout/behavior/styling changes

Projects

None yet

Milestone

v3.5-doc

Development

Successfully merging this pull request may close these issues.

2 participants

Back | FazBrowse Home | New Git URL