DOC: fix levels in user/explain/figure #26110

jklymak · 2023-06-12T00:56:51Z

PR summary

This fixes user/explain/figure, user/explain/axes, user/explain/artists to have a more conventional TOC page, followed by all the sub-pages. This is more like what sphinx expects, and makes the relevant sections show up as peers in the TOC.

Note there are no content changes other than the new TOC pages.

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

jklymak · 2023-06-13T00:01:16Z

As an aside, learned that you can do

.. toctree::
    :maxdepth: 2

    axes_intro

.. toctree::
    :maxdepth: 1

    arranging_axes
    colorbar_placement

And the TOC in the sidebar will show all of the entries, but the page will render with a nested TOC with just the first entry expanded.

jklymak · 2023-06-13T00:02:10Z

BTW, @story645 I'm all for having these TOCs be more visual, perhaps even with gallery-like cards. But I think these fixes should go in first just to get it organized better.

rcomer · 2023-06-13T06:26:55Z

I like the the change to the TOCs, but I feel like something is now missing from the top level figure page. Maybe just a very basic description of what a figure is for between the title and the code block?

jklymak · 2023-06-13T14:10:36Z

Ooops, yes, I meant to do that.

I also made the users_explain/index.rst into cards and maxdepth: 2 for better skim-ability. Some of the cards will need rebalancing later.

jklymak · 2023-06-13T14:48:20Z

https://output.circle-artifacts.com/output/job/bd5db14f-19b4-4a3d-9fdb-0884aca17cd4/artifacts/0/doc/build/html/users/explain/index.html

galleries/users_explain/figure/index.rst

story645 · 2023-06-13T19:15:48Z

. But I think these fixes should go in first just to get it organized better.

Yeah that's fine - I agree in that like I think a good follow up will be reference pictures anchoring each section, but I respect keeping that discussion away from this one.

story645

Accidentally did a ton of content changes, (didn't see what was just moved from other file til I did the review 🤦‍♀️ ) let me know if I should push into their own PR. Basically, I'm concerned that we're doing the thing we do a lot in the docs of showing how to use something without really explaining what it is.

Otherwise, small organization suggestions that I do want addressed since I think the catch all pile at the end doesn't help w/ discoverability.

And my most nit nit is is there a way to remove the more reading link:

story645 · 2023-06-15T19:47:37Z

galleries/users_explain/index.rst

+
+            axis/index
+            colors/index
+            text/index
+            animations/index
+            toolkits/index


Um can these be sorted out to the cards with related content?

axis/index -> axes
colors/index -> make this a card and show the second level
animations -> quickstart (this was always intended as a you don't need to know much tutorial)
text -> I would make this a card and show the second level 'cause again the annotation tutorial is buried
toolkits -> own card

I've reverted the changes to users_explain/index.rst so that can be in a separate PR

story645 · 2023-06-15T19:50:39Z

galleries/users_explain/artists/artist_intro.rst

+
+Usually we do not instantiate Artists directly, but rather use a plotting
+method on `~.axes.Axes`.  Some examples of plotting methods and the Artist
+object they create is given below:


Suggested change

object they create is given below:

object they create are given below:

story645 · 2023-06-15T19:52:19Z

galleries/users_explain/artists/artist_intro.rst

+Note that ``plot`` returns a _list_ of lines because you can pass in multiple x,
+y pairs to plot.  The line has been added to the Axes, and we can retrieve the


Suggested change

Note that ``plot`` returns a _list_ of lines because you can pass in multiple x,

y pairs to plot. The line has been added to the Axes, and we can retrieve the

Note that ``plot`` returns a _list_ of lines because it generates multiple line plots when given multiple x,y pairs as input. The line has been added to the Axes, and we can retrieve the

little nit to tie return more closely to the visual generated

story645 · 2023-06-15T19:52:57Z

galleries/users_explain/artists/artist_intro.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Getting the ``lines`` object gives us access to all the properties of the
+Line2D object.  So if we want to change the *linewidth* after the fact, we can do so using `.Artist.set`.


Suggested change

Line2D object. So if we want to change the *linewidth* after the fact, we can do so using `.Artist.set`.

Line2D object. If we want to change the *linewidth* after the fact, we can do so using `.Artist.set`.

story645 · 2023-06-15T19:55:56Z

galleries/users_explain/artists/artist_intro.rst

+We can interrogate the full list of settable properties with
+`matplotlib.artist.getp`:


Suggested change

We can interrogate the full list of settable properties with

`matplotlib.artist.getp`:

`matplotlib.artist.getp` returns the full list of settable properties:

story645 · 2023-06-15T21:45:14Z

galleries/users_explain/axes/axes_intro.rst

+
+The Axes class also has helpers to deal with Axis ticks and their labels.  Most straight-forward is `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` which manually set the tick locations and optionally their labels.  Minor ticks can be toggled with `~.axes.Axes.minorticks_on` or `~.axes.Axes.minorticks_off`.
+
+Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green:


Suggested change

Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green:

Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom, color the ticks red, and color the ticklabels green:

story645 · 2023-06-15T22:36:57Z

galleries/users_explain/figure/figure_intro.rst

+When looking at Matplotlib visualization, you are almost always looking at
+Artists placed on a `~.Figure`.  In the example above, the figure is the


Suggested change

When looking at Matplotlib visualization, you are almost always looking at

Artists placed on a `~.Figure`. In the example above, the figure is the

The `~.Figure` object roughly corresponds to the total drawing area of an image. Usually, a Figure is the top level artist in the Matplotlib draw tree, which means it contains all the other artists that have been added to the image. The Figure and its contents are what gets rendered to a screen or file. `~.Subfigure` objects can be rendered independently or as part of the main `Figure`.

In the example above, the figure is the

Added some explanatory text, added the bit about subfigures b/c folks frequently ask to be able to render Axes.

story645 · 2023-06-15T22:40:32Z

galleries/users_explain/figure/figure_intro.rst

+Users typically want an Axes or a grid of Axes when they create a Figure, so in
+addition to `~.pyplot.figure`, there are convenience methods that return both
+a Figure and some Axes.  A simple grid of Axes can be achieved with
+`.pyplot.subplots` (which
+simply wraps `.Figure.subplots`):
+
+.. plot::
+    :include-source:
+
+    fig, axs = plt.subplots(2, 2, figsize=(4, 3), layout='constrained')
+
+More complex grids can be achieved with `.pyplot.subplot_mosaic` (which wraps
+`.Figure.subplot_mosaic`):
+
+.. plot::
+    :include-source:
+
+    fig, axs = plt.subplot_mosaic([['A', 'right'], ['B', 'right']],
+                                  figsize=(4, 3), layout='constrained')
+    for ax_name in axs:
+        axs[ax_name].text(0.5, 0.5, ax_name, ha='center', va='center')
+


I don't like that this is yet another mini-tutorial on subplots. This should just be something like
Typically data is plotted on an axes. To add one to a figure, see :ref: axes

story645 · 2023-06-15T22:43:05Z

galleries/users_explain/figure/figure_intro.rst

+The `~.FigureBase` class has a number of methods to add artists to a `~.Figure` or
+a `~.SubFigure`.  By far the most common are to add Axes of various configurations
+(`~.FigureBase.add_axes`, `~.FigureBase.add_subplot`, `~.FigureBase.subplots`,
+`~.FigureBase.subplot_mosaic`) and subfigures (`~.FigureBase.subfigures`).  Colorbars
+are added to Axes or group of Axes at the Figure level (`~.FigureBase.colorbar`).
+It is also possible to have a Figure-level legend (`~.FigureBase.legend`).
+Other Artists include figure-wide labels (`~.FigureBase.suptitle`,
+`~.FigureBase.supxlabel`, `~.FigureBase.supylabel`) and text (`~.FigureBase.text`).
+Finally, low-level Artists can be added directly using `~.FigureBase.add_artist`
+usually with care being taken to use the appropriate transform.  Usually these
+include ``Figure.transFigure`` which ranges from 0 to 1 in each direction, and
+represents the fraction of the current Figure size, or ``Figure.dpi_scale_trans``
+which will be in physical units of inches from the bottom left corner of the Figure
+(see :ref:`transforms_tutorial` for more details).
+


Can this be broken up into bullets or distilled down to the most important bits? I'm concerned that this is a wall of text.

story645 · 2023-06-15T22:43:26Z

galleries/users_explain/figure/figure_intro.rst

+Saving Figures
+==============
+
+Finally, Figures can be saved to disk using the `~.Figure.savefig` method.


Suggested change

Finally, Figures can be saved to disk using the `~.Figure.savefig` method.

Figures can be saved to disk using the `~.Figure.savefig` method.

don't assume order of reading

jklymak · 2023-06-15T23:02:57Z

Yeah, this only moved things, so if you want changes to the actual content, happy to look at PRs that do that.

The catchall is inelegant, but the whole top index needs work. The main point here is fixing the users/explain/*/index etc so that they are just indexes and the sub info are peers instead of the awkward. I did have a version where each item was its own card, but that is really worse as they're a bunch of very empty cards. I think we can follow up on that and that the proposed structure here is better than what we have. If you'd prefer I can revert the user/explain/index changes, and make a new PR to mess around with that.

story645 · 2023-06-15T23:28:51Z

I did have a version where each item was its own card, but that is really worse as they're a bunch of very empty cards.

I think I'm proposing a mix and match, which is kind of what I'm doing in #26086

jklymak · 2023-06-16T01:26:07Z

I think I did mix and match. The subjects with substantive number of sub-headings have a separate card. Then there are the catch-alls.

story645 · 2023-06-16T01:43:20Z

Then there are the catch-alls

My problem with the catch alls is that they don't solve the major problem I'm having with both the user guide and the tutorial page, which is that the tutorials in the text and color section are no longer discoverable.

jklymak · 2023-06-16T02:29:31Z

Sure agreed that definitely needs to be fixed. But that is orthogonal to this pr.

jklymak · 2023-06-16T18:59:53Z

I've reverted the change to users/explain/index.
this PR largely only moved material, it didn't edit anything in the moved files. If there are changes desired to the moved material, those should be their own PR or issue, and not part of reviewing this PR.
the PR has new intro paragraphs for explain/figure/index, explain/axes/index, and explain/artist/index and a figure in each of those. These are copied almost verbatim from explain//_intro.rst.

rcomer

I’ve not been through in detail, only clicked around the built docs. I think they look great! Since @story645 has been through the details and already approved, I think this is good to go.

@jklymak do you want to squash the commits? Either way feel free to self merge.

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>

jklymak added the Documentation label Jun 12, 2023

jklymak force-pushed the doc-fix-levels-user-explain branch from 29865c6 to 038d067 Compare June 12, 2023 01:06

rcomer reviewed Jun 13, 2023

View reviewed changes

galleries/users_explain/figure/index.rst Outdated Show resolved Hide resolved

tacaswell added this to the v3.8.0 milestone Jun 15, 2023

story645 requested changes Jun 15, 2023

View reviewed changes

story645 requested a review from rcomer June 16, 2023 23:08

story645 mentioned this pull request Jun 16, 2023

Adding index explanation to 'Controlling and Labelling Axis Objects" #25805

Closed

3 tasks

story645 approved these changes Jun 16, 2023

View reviewed changes

rcomer approved these changes Jun 17, 2023

View reviewed changes

DOC: fix levels in user/explain/figure

9ec6407

Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>

jklymak force-pushed the doc-fix-levels-user-explain branch from 12c26ce to 9ec6407 Compare June 17, 2023 11:06

jklymak merged commit f329eb8 into matplotlib:main Jun 17, 2023

jklymak deleted the doc-fix-levels-user-explain branch June 17, 2023 15:41

jklymak mentioned this pull request Jun 17, 2023

Doc cards user explain #26141

Merged

5 tasks

rcomer mentioned this pull request Jul 1, 2023

[Doc]: users/explain bare index looks bad #25493

Closed

story645 mentioned this pull request Jul 13, 2023

DOC: remove users_explain/axis #26279

Merged

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: fix levels in user/explain/figure #26110

DOC: fix levels in user/explain/figure #26110

jklymak commented Jun 12, 2023 •

edited

Loading

jklymak commented Jun 13, 2023

jklymak commented Jun 13, 2023

rcomer commented Jun 13, 2023

jklymak commented Jun 13, 2023

jklymak commented Jun 13, 2023

story645 commented Jun 13, 2023

story645 left a comment •

edited

Loading

story645 Jun 15, 2023

jklymak Jun 16, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

story645 Jun 15, 2023

jklymak commented Jun 15, 2023

story645 commented Jun 15, 2023

jklymak commented Jun 16, 2023

story645 commented Jun 16, 2023

jklymak commented Jun 16, 2023

jklymak commented Jun 16, 2023

rcomer left a comment

	object they create is given below:
	object they create are given below:

		Note that ``plot`` returns a _list_ of lines because you can pass in multiple x,
		y pairs to plot. The line has been added to the Axes, and we can retrieve the

	Line2D object. So if we want to change the linewidth after the fact, we can do so using `.Artist.set`.
	Line2D object. If we want to change the linewidth after the fact, we can do so using `.Artist.set`.

		We can interrogate the full list of settable properties with
		`matplotlib.artist.getp`:

	We can interrogate the full list of settable properties with
	`matplotlib.artist.getp`:
	`matplotlib.artist.getp` returns the full list of settable properties:


		The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` which manually set the tick locations and optionally their labels. Minor ticks can be toggled with `~.axes.Axes.minorticks_on` or `~.axes.Axes.minorticks_off`.

		Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green:

		When looking at Matplotlib visualization, you are almost always looking at
		Artists placed on a `~.Figure`. In the example above, the figure is the

	Finally, Figures can be saved to disk using the `~.Figure.savefig` method.
	Figures can be saved to disk using the `~.Figure.savefig` method.

DOC: fix levels in user/explain/figure #26110

DOC: fix levels in user/explain/figure #26110

Conversation

jklymak commented Jun 12, 2023 • edited Loading

PR summary

PR checklist

jklymak commented Jun 13, 2023

jklymak commented Jun 13, 2023

rcomer commented Jun 13, 2023

jklymak commented Jun 13, 2023

jklymak commented Jun 13, 2023

story645 commented Jun 13, 2023

story645 left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jklymak commented Jun 15, 2023

story645 commented Jun 15, 2023

jklymak commented Jun 16, 2023

story645 commented Jun 16, 2023

jklymak commented Jun 16, 2023

jklymak commented Jun 16, 2023

rcomer left a comment

Choose a reason for hiding this comment

jklymak commented Jun 12, 2023 •

edited

Loading

story645 left a comment •

edited

Loading