DOC: Constrained layout tutorial improvements #11388

ImportanceOfBeingErnest · 2018-06-06T19:13:52Z

PR Summary

It wasn't clear to me that constrained_layout needs to be activated before adding any subplots to a figure. I find this an important piece of information and added it in the constrained layout guide. Also see minimal discussion on gitter.

While doings so, I also improved some other parts of this guide, mainly adding or fixing links/references.

When reading I came across a function .arange_subplotspecs which seems to not exist anywhere in the code base. Suggestions on how to change that could still be incoorporated here.

attn. @jklymak (who wrote that guide and should hence be the expert to review this.)

PR Checklist

Documentation is sphinx and numpydoc compliant

timhoffm

Looks good overall. Just some minor ReST/Sphinx issues.

timhoffm · 2018-06-06T19:32:35Z

tutorials/intermediate/constrainedlayout_guide.py

@@ -83,7 +99,7 @@ def example_plot(ax, fontsize=12, nodec=False):
    example_plot(ax)

 ###############################################################################
-# Specifying `constrained_layout=True` in the call to `plt.subplots`
+# Specifying ``constrained_layout=True`` in the call to ``plt.subplots``


Using plt.subplots(..., constrained_layout=True) causes ...

The sentence wasn't written by me, but I actually like it as it is. Otherwise it's too much doubled

Using __code__ cause x to happen: __code__

Ok, then leave it. The sentence feels quite verbose to me, but I won't start a discussion here.

timhoffm · 2018-06-06T19:35:11Z

tutorials/intermediate/constrainedlayout_guide.py

@@ -102,9 +118,9 @@ def example_plot(ax, fontsize=12, nodec=False):
 #
 # .. note::
 #
-#   For the `pcolormesh` kwargs (``pc_kwargs``) we use a dictionary.
+#   For the `~axes.Axes.pcolormesh` kwargs (``pc_kwargs``) we use a dictionary.


~.Axes.pcolormesh (otherwise it would have to be ~axes._axes.Axes.pcolormesh)

This is the error I make most often with this kind of format. I always forget the leading dot.

~.axes.Axes.pcolormesh works fine. I've been using this quite often in recent PRs. This is because axes/__init__.py has from ._axes import * in it. Hence matplotlib.axes.Axes.pcolormesh is valid.

timhoffm · 2018-06-06T19:37:30Z

tutorials/intermediate/constrainedlayout_guide.py

 #   Below we will assign one colorbar to a number of axes each containing
-#   a `ScalarMappable`; specifying the norm and colormap ensures
+#   a `~cm.ScalarMappable`; specifying the norm and colormap ensures


Not linking. Not sure why. is ; after ` allowed?

As said, I always forget the leading dot.

timhoffm · 2018-06-06T19:39:38Z

tutorials/intermediate/constrainedlayout_guide.py

 #
-# - `use`: Whether to use constrained_layout. Default is False
-# - `w_pad`, `h_pad`    Padding around axes objects.
+# - *use*: Whether to use constrained_layout. Default is False


I would tend to use double backticks. But don't really care too much here.

You're right, one should be consistent. Double backticks probably make it clearer that this is some code that is entered somewhere.

timhoffm · 2018-06-06T19:39:59Z

tutorials/intermediate/constrainedlayout_guide.py

-# to `ax.set_position()` will set the axes so constrained_layout has no
-# effect on it anymore.  (Note that constrained_layout still leaves the space
-# for the axes that is moved).
+# to `~.axes.Axes.set_position()` will set the axes so constrained_layout has


Second most often error. Forget to remove brackets.

I think brackets are allowed. I was questioning the ~.axes part because I did not realize the wildcard import in axes.

timhoffm · 2018-06-06T19:42:42Z

tutorials/intermediate/constrainedlayout_guide.py

-# In the code, this is accomplished by the entries in `.do_constrained_layout`
-# like::
+# In the code, this is accomplished by the entries in
+# ``.do_constrained_layout`` like::


Either no leading dot (and possibly trailing parentheses) or a proper link.

Cannot link to it, because that is a method from a private module which does not occur inside the docs. One may ask in general why all those methods are exposed here, while not being documented, but there might be a reason, so I'm not cutting this part.

timhoffm · 2018-06-06T19:43:00Z

tutorials/intermediate/constrainedlayout_guide.py

@@ -589,7 +606,7 @@ def docomplicated(suptitle=None):
 # much smaller than the left-hand, so the right-hand layoutboxes are smaller.
 #
 # The Subplotspec boxes are laid out in the code in the subroutine
-# `.arange_subplotspecs`, which simply checks the subplotspecs in the code
+# ``.arange_subplotspecs``, which simply checks the subplotspecs in the code


Either no leading dot (and possibly trailing parentheses) or a proper link.

This is the method or function that does not even exists. Maybe @jklymak can comment here and in the cases below how this is to be understood and how those names are in general to be layouted. Maybe there is a deeper sense in the leading-dot-notation here?

I assume that it was thought to be a link. `.arange_subplotspecs` would be perfectly fine if the module wasn't private.

Oh stupid, of course you're right. Will change that.

timhoffm · 2018-06-06T19:43:13Z

tutorials/intermediate/constrainedlayout_guide.py

@@ -627,9 +644,9 @@ def docomplicated(suptitle=None):
 # number of columns (one in this example).
 #
 # The colorbar layout logic is contained in `~matplotlib.colorbar.make_axes`
-# which calls `._constrained_layout.layoutcolorbarsingle`
+# which calls ``._constrained_layout.layoutcolorbarsingle``


No leading dot (and possibly trailing parentheses).

timhoffm · 2018-06-06T19:43:23Z

tutorials/intermediate/constrainedlayout_guide.py

 # for cbars attached to a single axes, and
-# `._constrained_layout.layoutcolorbargridspec` if the colorbar is associated
+# ``._constrained_layout.layoutcolorbargridspec`` if the colorbar is associated


No leading dot (and possibly trailing parentheses).

timhoffm · 2018-06-06T19:44:59Z

tutorials/intermediate/constrainedlayout_guide.py

@@ -713,7 +730,7 @@ def docomplicated(suptitle=None):
 # the axes position in made the same size as the occupied Axes positions.
 #
 # This is done at the start of
-# `~._constrained_layout.do_constrained_layout` (``hassubplotspec``).
+# ``~._constrained_layout.do_constrained_layout`` (``hassubplotspec``).


No leading dot (and possibly trailing parentheses).

jklymak · 2018-06-06T22:59:24Z

I’m at a meeting and can’t work on this. If you guys think it’s an improvement I’m all for it. Often the person who wrote the first draft shouldn’t write the second. OTOH happy to try to help if any technical questions. But if none feel free to merge w/o me!

ImportanceOfBeingErnest · 2018-06-06T23:17:00Z

From my side this is "fixed" and can be merged as is.

But I think in the long run, the lower part of this guide could benefit from being proof-read by you again. Possibly this is all fine, but I sure lack the expertise to know. What makes me wonder is that it refers to a function that does not exist and in general explains stuff that you cannot understand without deeply inspecting the private module itself.

jklymak

Thanks a lot!

timhoffm approved these changes Jun 6, 2018

View reviewed changes

ImportanceOfBeingErnest force-pushed the doc_constrained_layout_improvement branch 2 times, most recently from 6396b50 to 79873aa Compare June 6, 2018 21:17

Constrained layout tutorial improvements

553bfab

ImportanceOfBeingErnest force-pushed the doc_constrained_layout_improvement branch from 79873aa to 553bfab Compare June 7, 2018 20:50

jklymak approved these changes Jun 9, 2018

View reviewed changes

jklymak merged commit 9d81809 into matplotlib:master Jun 9, 2018

ImportanceOfBeingErnest deleted the doc_constrained_layout_improvement branch June 15, 2018 00:35

QuLogic added this to the v3.0.0 milestone Nov 27, 2018

Uh oh!

DOC: Constrained layout tutorial improvements #11388

DOC: Constrained layout tutorial improvements #11388

Uh oh!

Conversation

ImportanceOfBeingErnest commented Jun 6, 2018

PR Summary

PR Checklist

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jklymak commented Jun 6, 2018

Uh oh!

ImportanceOfBeingErnest commented Jun 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jklymak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ImportanceOfBeingErnest commented Jun 6, 2018 •

edited

Loading