plt.subplots and plt.figure docstring changes #11382

fredrik-1 · 2018-06-05T22:14:06Z

Same small changes in plt.subplots and plt.figure docstrings and the plt.subplots docstring was copied to the figure.subplots docstring.

The changes was mainly in the links to other documentation

PR Checklist

Has Pytest style unit tests
Code is PEP 8 compliant
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

timhoffm

Thanks! Looks good overall. I'd like still some minor changes.

timhoffm · 2018-06-05T22:24:19Z

lib/matplotlib/pyplot.py


    frameon : bool, optional, default: True
        If False, suppress drawing the figure frame.

-    FigureClass : class derived from matplotlib.figure.Figure
+    FigureClass : class derived from the :class:`~matplotlib.figure.Figure` class.


FigureClass : subclass of `~matplotlib.figure.Figure`

should be sufficient.

timhoffm · 2018-06-05T22:25:59Z

lib/matplotlib/pyplot.py

        Optionally use a custom Figure instance.

    clear : bool, optional, default: False
        If True and the figure already exists, then it is cleared.

    Returns
    -------
-    figure : Figure
+    figure : :class:`~matplotlib.figure.Figure` object


figure : `~matplotlib.figure.Figure`

timhoffm · 2018-06-05T22:26:32Z

lib/matplotlib/pyplot.py

-        pylab interface. Additional kwargs will be passed to the figure init
-        function.
+        pylab interface. Additional kwargs will be passed to the 
+        :class:`~matplotlib.figure.Figure` init function.


We use the sphinx default role 'obj' so this can be simplified. No need for the Prefix. Within text blocks, we use the shortest form possible.

`~matplotlib.figure.Figure` or maybe even `.Figure` is enough.

I have mostly looked at the other docstrings in regard to prefixes. Are there any directives for how to use them (couldn't find anything in the documentation)? :func: and :meth: adds parenthesis but are there any other reasons to use them?

Unfortunately, the docs on documentation is not up-to-date in that respect. See Citing other types in #10225.

That using the default role does not add parentheses is a bug in Sphinx: sphinx-doc/sphinx#4409 I wouldn't make that a criterion how to write our docstrings.

I wanted to know if we should use for example
:class: .Figure or just .Figure

Should :class:, :meth:, :func:, :mod: etc be used or not? I haven't found anything about this anywhere but some docstrings include those but I believe that many don't.

Citing other types in #10225 is the current proposal.

Don't rely too much on what's currently present in the docs. We have a lot of legacy code that has not yet been updated to and still uses :class:`.Figure` everywhere.

Ok, so :class: etc should not be used? I found that section confusing when it seems to only talk about when to use ~matplotlib.markers.MarkerStyle or .MarkerStyle and not anything about :class: etc.

Oh sorry, I didn't read carefully.

:class: is basically almost never needed (except for rare cases where name may not be unique otherwise, e.g. cycler).

I updated the code.

I still don't understand what is the best practice, convention and what works in regard to :func:, :class: etc.

I need to use :func: and :meth: in places where I don't understand why. It seems to not look outside of the actual function or method without them when searching for the function or method even though I even used the full link.

timhoffm · 2018-06-05T22:32:00Z

lib/matplotlib/pyplot.py

-        width, height in inches. If not provided, defaults to rc
-        figure.figsize.
+        width, height in inches. If not provided, defaults to 
+        :rc:`figure.figsize`.


It was suggested in another thread, that we add the default rcParams value in brackets, such as

defaults to :rc:`figure.figsize` (``[6.4, 4.8]``)

I think that's a reasonable addition. While :rc: could be extended to write that as well, there's a benefit in having the value within the docstring itself.

I dont like the look in the rendered html
rcParams["figure.figsize"] ([6.4, 4.8])
rcParams["figure.figsize"], ([6.4, 4.8])

Should one of those be used or are there any better way?

This was just suggested in another thread. We do not have a convention yet and I have no clear idea how this formatting should be. Maybe rcParams["figure.figsize"] = [6.4, 4.8]?. Do you have any suggestions?

timhoffm · 2018-06-05T22:37:02Z

lib/matplotlib/pyplot.py


    ax : Axes object or array of Axes objects.

-        ax can be either a single :class:`matplotlib.axes.Axes` object or an
+        ax can be either a single :class:`~matplotlib.axes.Axes` object or an


timhoffm · 2018-06-07T17:36:13Z

lib/matplotlib/figure.py

+        ax : Axes object or array of Axes objects.
+            *ax* can be either a single `~matplotlib.axes.Axes` object or
+            an array of Axes objects if more than one subplot was created. The
+            dimensions of the resulting array can be controlled with the squeeze


PEP-8 claims the line is too long: break before "squeeze" That's what breaks the Travis build.

timhoffm

Good to go modulo the PEP-8 error.

NelleV · 2018-06-09T17:22:28Z

Thanks @fredrik-1 !

timhoffm reviewed Jun 5, 2018

View reviewed changes

fredrik-1 force-pushed the subplots_docs branch 3 times, most recently from ac8c3d1 to 31f709a Compare June 7, 2018 12:24

timhoffm reviewed Jun 7, 2018

View reviewed changes

timhoffm approved these changes Jun 7, 2018

View reviewed changes

fredrik-1 force-pushed the subplots_docs branch from 31f709a to 00fbb7d Compare June 7, 2018 19:51

subplots and figure docstring changes

e0ef3ff

fredrik-1 force-pushed the subplots_docs branch from 00fbb7d to e0ef3ff Compare June 8, 2018 16:40

NelleV merged commit 7f2b48b into matplotlib:master Jun 9, 2018

QuLogic added this to the v3.0 milestone Jun 10, 2018

fredrik-1 deleted the subplots_docs branch June 10, 2018 07:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

plt.subplots and plt.figure docstring changes #11382

plt.subplots and plt.figure docstring changes #11382

fredrik-1 commented Jun 5, 2018

timhoffm left a comment

timhoffm Jun 5, 2018

timhoffm Jun 5, 2018

timhoffm Jun 5, 2018

fredrik-1 Jun 6, 2018

timhoffm Jun 6, 2018

fredrik-1 Jun 6, 2018

timhoffm Jun 6, 2018

fredrik-1 Jun 6, 2018

timhoffm Jun 6, 2018

fredrik-1 Jun 7, 2018

timhoffm Jun 5, 2018

fredrik-1 Jun 6, 2018

timhoffm Jun 6, 2018

timhoffm Jun 5, 2018

timhoffm Jun 7, 2018 •

edited

Loading

timhoffm left a comment

NelleV commented Jun 9, 2018

plt.subplots and plt.figure docstring changes #11382

plt.subplots and plt.figure docstring changes #11382

Conversation

fredrik-1 commented Jun 5, 2018

PR Checklist

timhoffm left a 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

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

timhoffm Jun 7, 2018 • edited Loading

Choose a reason for hiding this comment

timhoffm left a comment

Choose a reason for hiding this comment

NelleV commented Jun 9, 2018

timhoffm Jun 7, 2018 •

edited

Loading