Skip to content

Conversation

NelleV
Copy link
Member

@NelleV NelleV commented Jan 17, 2020

Added tight_layout and kwargs argument description to plt.figure.

@tacaswell tacaswell added this to the v3.3.0 milestone Jan 20, 2020
@@ -450,6 +450,16 @@ def figure(num=None, # autoincrement if None, else integer from 1-N
clear : bool, default: False
If True and the figure already exists, then it is cleared.

tight_layout : bool or dict, default: :rc:`figure.autolayout`
Copy link
Contributor

Choose a reason for hiding this comment

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

I guess this doesn't need to be listed explicitly here? It's a normal Figure kwarg anyways, so documented there; if anything we may rather want to promote the use of constrained_layout?

Copy link
Member Author

Choose a reason for hiding this comment

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

Sure, nothing really has to be listed explicitly here. All the arguments here but one are indeed duplicates of figure.Figure.

Copy link
Member

Choose a reason for hiding this comment

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

I am fine with tight_layout here, but should also add constrained_layout (can be a diff PR). The sphinx link below needs to be fixed (leading dot?, I really find sphinx documentation to be hard to make valid cross-references for).

Copy link
Contributor

Choose a reason for hiding this comment

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

re: sphinx references: any reference to something not in the current module needs to be prefixed by a dot. Possibly with the module name in front to disambiguate further (e.g. between .Axes.plot and .pyplot.plot, otherwise sphinx reasonably complains that it doesn't know which one to use), but not necessary if there is no ambiguity (e.g. .Figure). What gets printed in the rendered html is what you put between the backquotes, minus the leading dot, unless you add a tilde in front of it, in which case all the context is stripped so e.g. ~.Axes.plot and ~.pyplot.plot both get rendered as plot.
(This is made slightly more complicated by the fact that often we have docstrings that are originally defined in one module but end up also in an object defined in another module (via inheritance); sphinx is not able to follow that and will complain if the inherited docstring "wanted" to refer to objects in the first module without using a leading dot.)
Also anything referring to something not in matplotlib at all (i.e. numpy, etc.) needs to be fully qualified.

@NelleV
Copy link
Member Author

NelleV commented Jan 21, 2020

Feel free to close if you feel this shouldn't go in.

@NelleV NelleV force-pushed the figure_doc_tight_layout branch from 30b8645 to a3b8a32 Compare January 22, 2020 17:39
@NelleV NelleV force-pushed the figure_doc_tight_layout branch from a3b8a32 to cc7e3a4 Compare January 23, 2020 08:15
@QuLogic
Copy link
Member

QuLogic commented May 5, 2020

So @anntzer / @jklymak, can you make a decision here? I don't think this needs to wait for 3.4 if it's going in, and if it's not, well then, it's not.

@jklymak
Copy link
Member

jklymak commented May 5, 2020

Sorry, I'd missed that the was fixed....

@jklymak jklymak merged commit 10b0b48 into matplotlib:master May 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants