Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: plotting section for Users Guide #29124

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

DOC: plotting section for Users Guide #29124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19d4421
DOC: just new labels
jklymak Nov 2, 2024
f3a6f53
DOC: user guide section on plotting methods
jklymak Nov 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions doc/users/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,15 @@ Using Matplotlib

explain/axes/index

.. grid-item-card::
:padding: 2

.. toctree::
:maxdepth: 2
:includehidden:

explain/plotting/index


.. grid-item-card::
:padding: 2
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/contour_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _contour_demo:
Copy link
Member

Choose a reason for hiding this comment

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

Is there a reason you introduce labels to a lot of examples? Generally, we've been referencing examples via the doc :doc:`/gallery/images_contours_and_fiels/contour_demo` . See also https://matplotlib.org/devdocs/devel/document.html#refer-to-other-documents-and-sections.

Copy link
Member Author

Choose a reason for hiding this comment

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

Because if we have to re-arrange things all these hard links break, whereas labeled references do not break.

Copy link
Member

Choose a reason for hiding this comment

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

IMHO this is a case of YAGNI. We are quite conservative on the structure because it translates to public URLs. And if we really want to change, that’s a quite easy search&replace, which we need to anyway, because our current way of referencing examples is predominantly doc based.

This makes the PR look more complicated and I’ve some reservations whether it’s actually better to reference examples using labels.

Copy link
Member

Choose a reason for hiding this comment

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

I don't mind it b/c we've done some thrashing on the galleries, but I think it might make both discussions easier if it was spun out into a separate PR

Copy link
Member Author

Choose a reason for hiding this comment

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

IMHO this is a case of YAGNI. We are quite conservative on the structure because it translates to public URLs. And if we really want to change, that’s a quite easy search&replace, which we need to anyway, because our current way of referencing examples is predominantly doc based.

This was a huge barrier to making doc changes 5 or so years ago. Since then we introduced the redirect mechanism which has allowed things to be moved. It is likely true that our predominant way of referencing things is :doc: based, I'd argue :ref: is much more flexible. Certainly :ref: is used in many places as well.

Regardless, I don't think this really affects this PR. I made zero substantive changes to any of the other files - I just added the reference label. I also didn't change any :doc: calls elsewhere.

Copy link
Member

@timhoffm timhoffm Jan 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It is likely true that our predominant way of referencing things is :doc: based

To give a number: 7 examples have labels. but we have 150 :doc: references.

Regardless, I don't think this really affects this PR.

I beg to differ:

  • Substantially introducing label-based referencing for examples is a new paradigm, which I don't want to introduce as a side-effect. I'm not going here into the pros and cons, even tough I have opinions. This deserves a dedicated discussion. It would be fine if you simultaneously have open an issue on this.
  • It further bloats a nontheless giant PR to 51 files and >1500 lines. I simply refuse to review this size of PR unless there are strong arguments that it cannot be splitted and the huge PR is sub-structured into reasonable commits.

So the effect is at least I'm not looking at this, which is fine as long as you find other reviewers. I'm just giving my perspective. Others would have to comment on why they haven't reviewed.

Copy link
Member Author

Choose a reason for hiding this comment

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

Substantially introducing label-based referencing for examples is a new paradigm, which I don't want to introduce as a side-effect.

Again, this isn't new, or just being introduced now - we have had label-based referencing for as long as I have been contributing. All this PR does is add labels, it doesn't change any existing references. If I put in a stand-alone PR with just the labels, that is all it would be - a bunch of labels not used anywhere yet. I can certainly do that if you like, but I'm not sure what the point is.

To give a number: 7 examples have labels. but we have 150 :doc: references.

An aside, for sure, but :ref: is used 738 times in our docs, and a quick skim indicates that they are all label based references to elsewhere in the docs. :doc: is used 291 times. Perhaps you are making a distinction between the gallery and the rest of the docs?

Copy link
Member

@story645 story645 Jan 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@jklymak do you have a strong objection to splitting off the labeling PR from the plotting guide PR? I tend to review docs on my phone so it's a lot to scroll past, and as the back and forth with Tim is showing there's a whole separate conversation to be had about labeling.

If I put in a stand-alone PR with just the labels, that is all it would be - a bunch of labels not used anywhere yet

That's fine, folks do staged PRs all the time. Just say it's for this PR. Or put adding the labels in a separate first commit so reviewers can filter it out.

Copy link
Member Author

Choose a reason for hiding this comment

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

I could do both those things if it makes things easier.

Copy link
Member Author

Choose a reason for hiding this comment

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

Done


============
Contour Demo
============
Expand Down
1 change: 1 addition & 0 deletions galleries/examples/images_contours_and_fields/contourf_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
"""
.. _contourf_demo:
=============
Contourf demo
=============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/contourf_log.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _contourf_log:

============================
Contourf and log color scale
============================
Expand Down
4 changes: 4 additions & 0 deletions galleries/examples/images_contours_and_fields/image_antialiasing.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
"""
.. _image_antialiasing:

.. _image_resampling:

================
Image resampling
================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/image_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _image_demo:

========================
Many ways to plot images
========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/pcolor_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _pcolor_demo:

=============
pcolor images
=============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/pcolormesh_grids.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _pcolormesh_grids:

============================
pcolormesh grids and shading
============================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/plot_streamplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _plot_streamplot:

==========
Streamplot
==========
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/tricontour_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _tricontour_demo:

===============
Tricontour Demo
===============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/tricontour_smooth_delaunay.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _tricontour_smooth_delaunay:

==========================
Tricontour Smooth Delaunay
==========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/tricontour_smooth_user.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _tricontour_smooth_user:

======================
Tricontour Smooth User
======================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/tripcolor_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _tripcolor_demo:

==============
Tripcolor Demo
==============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/images_contours_and_fields/triplot_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _triplot_demo:

============
Triplot Demo
============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/lines_bars_and_markers/categorical_variables.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _categorical_variables:

==============================
Plotting categorical variables
==============================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/lines_bars_and_markers/eventplot_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _eventplot_demo:

==============
Eventplot demo
==============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/lines_bars_and_markers/fill_between_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _fill_between_demo:

===============================
Fill the area between two lines
===============================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/lines_bars_and_markers/step_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _step_demo:

=========
Step Demo
=========
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/bars3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _bars3d:

========================================
Create 2D bar graphs in different planes
========================================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/box3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _box3d:

===================
3D box surface plot
===================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/custom_shaded_3d_surface.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _custom_shaded_3d_surface:

=======================================
Custom hillshading in a 3D surface plot
=======================================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/intersecting_planes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _intersecting_planes:

===================
Intersecting planes
===================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/quiver3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _quiver3d:

==============
3D quiver plot
==============
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/stem3d_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _stem3d_demo:

=======
3D stem
=======
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/surface3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _surface3d:

=====================
3D surface (colormap)
=====================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/surface3d_2.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _surface3d_2:

========================
3D surface (solid color)
========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/surface3d_3.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _surface3d_3:

=========================
3D surface (checkerboard)
=========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/trisurf3d.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _trisurf3d:

======================
Triangular 3D surfaces
======================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/mplot3d/trisurf3d_2.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _trisurf3d_2:

===========================
More triangular 3D surfaces
===========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/boxplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _boxplot_artists:

=================================
Artist customization in box plots
=================================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/boxplot_color.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _boxplot_color:

=================================
Box plots with custom fill colors
=================================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/boxplot_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _boxplot_demo:

========
Boxplots
========
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/boxplot_vs_violin.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _boxplot_vs_violin:

===================================
Box plot vs. violin plot comparison
===================================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/customized_violin.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _customized_violin:

=========================
Violin plot customization
=========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/hexbin_demo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _hexbin_demo:

=====================
Hexagonal binned plot
=====================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/histogram_histtypes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _histogram_histtypes:

================================================================
Demo of the histogram function's different ``histtype`` settings
================================================================
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/histogram_multihist.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _histogram_multihist:

=====================================================
The histogram (hist) function with multiple data sets
=====================================================
Expand Down
1 change: 1 addition & 0 deletions galleries/examples/statistics/histogram_normalization.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
"""
.. redirect-from:: /gallery/statistics/histogram_features
.. _histogram_normalization:

===================================
Histogram bins, density, and weight
Expand Down
2 changes: 2 additions & 0 deletions galleries/examples/statistics/violinplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _violinplot:

==================
Violin plot basics
==================
Expand Down
2 changes: 2 additions & 0 deletions galleries/plot_types/3D/bar3d_simple.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _bar3d_simple:

==========================
bar3d(x, y, z, dx, dy, dz)
==========================
Expand Down
2 changes: 2 additions & 0 deletions galleries/plot_types/3D/surface3d_simple.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _surface3d_simple:

=====================
plot_surface(X, Y, Z)
=====================
Expand Down
2 changes: 2 additions & 0 deletions galleries/plot_types/3D/trisurf3d_simple.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
"""
.. _trisurf3d_simple:

=====================
plot_trisurf(x, y, z)
=====================
Expand Down
3 changes: 3 additions & 0 deletions galleries/plot_types/arrays/pcolormesh.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
"""
.. _pcolormesh:

===================
pcolormesh(X, Y, Z)
===================

Create a pseudocolor plot with a non-regular rectangular grid.

`~.axes.Axes.pcolormesh` is more flexible than `~.axes.Axes.imshow` in that
Expand Down
2 changes: 2 additions & 0 deletions galleries/users_explain/artists/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _users-guide-artists:

+++++++
Artists
+++++++
Expand Down
2 changes: 2 additions & 0 deletions galleries/users_explain/axes/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _users_guide_axes:

+++++++++++++++++
Axes and subplots
+++++++++++++++++
Expand Down
Loading