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

Skip to content

Commit 80eabbc

Browse files
story645story645
authored
Merge pull request #18372 from QuLogic/doc-refs
DOC: Fix various missing references and typos
2 parents b12b3f4 + 3656ac5 commit 80eabbc

19 files changed

+212
-376
lines changed

‎doc/api/docstring_api.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
************************
2+
``matplotlib.docstring``
3+
************************
4+
5+
.. automodule:: matplotlib.docstring
6+
:members:
7+
:undoc-members:
8+
:show-inheritance:

‎doc/api/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@ Matplotlib consists of the following submodules:
8787
container_api.rst
8888
contour_api.rst
8989
dates_api.rst
90+
docstring_api.rst
9091
dviread.rst
9192
figure_api.rst
9293
font_manager_api.rst

‎doc/api/prev_api_changes/api_changes_3.1.0.rst

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -767,11 +767,12 @@ The following signature related behaviours are deprecated:
767767
keyword.
768768
- The *interp_at_native* parameter to `.BboxImage`, which has had no effect
769769
since Matplotlib 2.0, is deprecated.
770-
- All arguments to the `.cbook.deprecated` decorator and `.cbook.warn_deprecated`
771-
function, except the first one (the version where the deprecation occurred),
772-
are now keyword-only. The goal is to avoid accidentally setting the "message"
773-
argument when the "name" (or "alternative") argument was intended, as this has
774-
repeatedly occurred in the past.
770+
- All arguments to the `~.cbook.deprecation.deprecated` decorator and
771+
`~.cbook.deprecation.warn_deprecated` function, except the first one (the
772+
version where the deprecation occurred), are now keyword-only. The goal is
773+
to avoid accidentally setting the "message" argument when the "name" (or
774+
"alternative") argument was intended, as this has repeatedly occurred in the
775+
past.
775776
- The arguments of `matplotlib.testing.compare.calculate_rms` have been renamed
776777
from ``expectedImage, actualImage``, to ``expected_image, actual_image``.
777778
- Passing positional arguments to `.Axis.set_ticklabels` beyond *ticklabels*
@@ -1073,11 +1074,12 @@ This only served as a helper to the private `.Axis._update_ticks`
10731074

10741075
Undeprecations
10751076
--------------
1076-
The following API elements have bee un-deprecated:
1077+
The following API elements have been un-deprecated:
10771078

1078-
- The *obj_type* kwarg to the `.cbook.deprecated` decorator.
1079-
- *xmin*, *xmax* kwargs to `.Axes.set_xlim` and *ymin*, *ymax* kwargs
1080-
to `.Axes.set_ylim`
1079+
- The *obj_type* keyword argument to the `~.cbook.deprecation.deprecated`
1080+
decorator.
1081+
- *xmin*, *xmax* keyword arguments to `.Axes.set_xlim` and *ymin*, *ymax*
1082+
keyword arguments to `.Axes.set_ylim`
10811083

10821084

10831085
New features

‎doc/api/testing_api.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
**********************
44

55

6+
:func:`matplotlib.test`
7+
=======================
8+
9+
.. autofunction:: matplotlib.test
10+
611
:mod:`matplotlib.testing`
712
=========================
813

‎doc/devel/MEP/MEP10.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,15 +159,15 @@ Implementation
159159
should be divided on a per-module basis so no single developer is
160160
over-burdened by it.
161161

162-
3. Reorganize the API docs using autosummary and `sphinx-autogen`.
162+
3. Reorganize the API docs using autosummary and ``sphinx-autogen``.
163163
This should hopefully have minimal impact on the narrative
164164
documentation.
165165

166166
4. Modify the example page generator (:file:`gen_rst.py`) so that it
167167
extracts the module docstring from the example and includes it in a
168168
non-literal part of the example page.
169169

170-
5. Use `sphinx-quickstart` to generate a new-style Sphinx Makefile.
170+
5. Use ``sphinx-quickstart`` to generate a new-style Sphinx Makefile.
171171
The following features in the current :file:`make.py` will have to be
172172
addressed in some other way:
173173

‎doc/devel/MEP/MEP12.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@ Status
1111
**Progress**
1212

1313
Initial changes added in 1.3. Conversion of the gallery is on-going.
14-
29 September 2015 - The last ``pylab_examples`` where `pylab` is imported has been converted over to use :mod:`matplotlib.pyplot` and `numpy`.
14+
29 September 2015 - The last ``pylab_examples`` where ``pylab`` is imported has
15+
been converted over to use :mod:`matplotlib.pyplot` and `numpy`.
1516

1617
Branches and Pull requests
1718
==========================

‎doc/devel/MEP/MEP14.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -265,16 +265,16 @@ Implementation
265265
==============
266266

267267
A concept of a "text engine" will be introduced. Each text engine
268-
will implement a number of abstract classes. The `TextFont` interface
268+
will implement a number of abstract classes. The ``TextFont`` interface
269269
will represent text for a given set of font properties. It isn't
270270
necessarily limited to a single font file -- if the layout engine
271271
supports rich text, it may handle a number of font files in a family.
272-
Given a `TextFont` instance, the user can get a `TextLayout` instance,
272+
Given a ``TextFont`` instance, the user can get a ``TextLayout`` instance,
273273
which represents the layout for a given string of text in a given
274-
font. From a `TextLayout`, an iterator over `TextSpans` is returned
274+
font. From a ``TextLayout``, an iterator over ``TextSpan``\ s is returned
275275
so the engine can output raw editable text using as few spans as
276276
possible. If the engine would rather get individual characters, they
277-
can be obtained from the `TextSpan` instance::
277+
can be obtained from the ``TextSpan`` instance::
278278

279279

280280
class TextFont(TextFontBase):
@@ -376,10 +376,10 @@ copy of the path for each character will be stored in the file.
376376
Special casing: The "usetex" functionality currently is able to get
377377
Postscript directly from TeX to insert directly in a Postscript file,
378378
but for other backends, parses a DVI file and generates something more
379-
abstract. For a case like this, `TextLayout` would implement
380-
`get_spans` for most backends, but add `get_ps` for the Postscript
379+
abstract. For a case like this, ``TextLayout`` would implement
380+
``get_spans`` for most backends, but add ``get_ps`` for the Postscript
381381
backend, which would look for the presence of this method and use it
382-
if available, or fall back to `get_spans`. This kind of special
382+
if available, or fall back to ``get_spans``. This kind of special
383383
casing may also be necessary, for example, when the graphics backend
384384
and text engine belong to the same ecosystem, e.g. Cairo and Pango, or
385385
MacOSX and CoreText.

‎doc/devel/MEP/MEP15.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ None so far.
1818
Abstract
1919
========
2020

21-
When one axis of a 2-dimensional plot if overridden via `~.Axes.set_xlim` or `~.Axes.set_ylim`,
22-
automatic scaling of the remaining axis should be based on the data that falls
23-
within the specified limits of the first axis.
21+
When one Axis of a 2-dimensional plot is overridden via `~.Axes.set_xlim` or
22+
`~.Axes.set_ylim`, automatic scaling of the remaining Axis should be based on
23+
the data that falls within the specified limits of the first Axis.
2424

2525
Detailed description
2626
====================

‎doc/devel/MEP/MEP22.rst

Lines changed: 21 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ reconfiguration.
3939

4040
This approach will make easier to create and share tools among
4141
users. In the far future, we can even foresee a kind of Marketplace
42-
for `Tools` where the most popular can be added into the main
42+
for ``Tool``\ s where the most popular can be added into the main
4343
distribution.
4444

4545
Detailed description
@@ -53,12 +53,12 @@ example see https://github.com/matplotlib/matplotlib/issues/2694 also
5353
the shortcuts are hardcoded and again not easily modifiable
5454
https://github.com/matplotlib/matplotlib/issues/2699
5555

56-
The proposed solution is to take the actions out of the `Toolbar` and
57-
the shortcuts out of the `Canvas`. This actions and shortcuts will be
58-
in the form of `Tools`.
56+
The proposed solution is to take the actions out of the ``Toolbar`` and the
57+
shortcuts out of the ``Canvas``. The actions and shortcuts will be in the form
58+
of ``Tool``\ s.
5959

60-
A new class `Navigation` will be the bridge between the events from
61-
the `Canvas` and `Toolbar` and redirect them to the appropriate `Tool`.
60+
A new class ``Navigation`` will be the bridge between the events from the
61+
``Canvas`` and ``Toolbar`` and redirect them to the appropriate ``Tool``.
6262

6363
At the end the user interaction will be divided into three classes:
6464

@@ -75,7 +75,8 @@ Implementation
7575
ToolBase(object)
7676
----------------
7777

78-
Tools can have a graphical representation as the `SubplotTool` or not even be present in the Toolbar as `Quit`
78+
Tools can have a graphical representation as the ``SubplotTool`` or not even be
79+
present in the Toolbar as ``Quit``.
7980

8081
The `.ToolBase` has the following class attributes for configuration at definition time
8182

@@ -93,7 +94,8 @@ The following instance attributes are set at instantiation:
9394
* keypress associated with the Tool Keymap
9495
* Call to navigation.trigger_tool(name)
9596
* set_figure(self, figure): Set the figure and navigation attributes
96-
* ``destroy(self, *args)``: Destroy the `Tool` graphical interface (if exists)
97+
* ``destroy(self, *args)``: Destroy the ``Tool`` graphical interface (if
98+
exists)
9799

98100
**Available Tools**
99101
* ToolQuit
@@ -137,7 +139,7 @@ NavigationBase
137139

138140
Defines the following attributes
139141
* canvas:
140-
* keypresslock: Lock to know if the `canvas` key_press_event` is
142+
* keypresslock: Lock to know if the ``canvas`` ``key_press_event`` is
141143
available and process it
142144
* messagelock: Lock to know if the message is available to write
143145

@@ -152,9 +154,9 @@ Public methods for **User use**:
152154
associated with the tool
153155
* set_tool_keymap(self, name, ``*keys``): Set the keys for the given tool
154156
* remove_tool(self, name): Removes tool from the navigation control.
155-
* add_tools(self, tools): Add multiple tools to `Navigation`
157+
* add_tools(self, tools): Add multiple tools to ``Navigation``
156158
* add_tool(self, name, tool, group=None, position=None): Add a tool
157-
to the Navigation
159+
to the ``Navigation``
158160
* tool_trigger_event(self, name, sender=None, canvasevent=None,
159161
data=None): Trigger a tool and fire the event
160162

@@ -168,20 +170,20 @@ ToolbarBase
168170
-----------
169171

170172
Methods for **Backend implementation**
171-
* add_toolitem(self, name, group, position, image, description,
172-
toggle): Add a toolitem to the toolbar. This method is a callback
173-
from `tool_added_event` (emitted by navigation)
174-
* set_message(self, s): Display a message on toolbar or in status bar
175-
* toggle_toolitem(self, name): Toggle the toolitem without firing
176-
event.
177-
* remove_toolitem(self, name): Remove a toolitem from the `Toolbar`
173+
174+
* ``add_toolitem(self, name, group, position, image, description, toggle)``:
175+
Add a toolitem to the toolbar. This method is a callback from
176+
``tool_added_event`` (emitted by navigation)
177+
* ``set_message(self, s)``: Display a message on toolbar or in status bar
178+
* ``toggle_toolitem(self, name)``: Toggle the toolitem without firing event.
179+
* ``remove_toolitem(self, name)``: Remove a toolitem from the ``Toolbar``
178180

179181

180182
Backward compatibility
181183
======================
182184

183185
For backward compatibility added 'navigation' to the list of values
184-
supported by :rc:`toolbar`, that is used for Navigation classes
186+
supported by :rc:`toolbar`, that is used for ``Navigation`` classes
185187
instantiation instead of the NavigationToolbar classes
186188

187189
With this parameter, it makes it transparent to anyone using the

‎doc/devel/MEP/MEP23.rst

Lines changed: 34 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Abstract
2323
========
2424

2525
Add the possibility to have multiple figures grouped under the same
26-
`FigureManager`
26+
`~.backend_template.FigureManager`
2727

2828
Detailed description
2929
====================
@@ -38,60 +38,65 @@ desirable to be able to group these under the same window
3838
[see](https://github.com/matplotlib/matplotlib/issues/2194).
3939

4040
The proposed solution modifies `.FigureManagerBase` to contain and manage more
41-
than one `canvas`. The settings parameter :rc:`backend.multifigure` control
41+
than one ``Canvas``. The settings parameter :rc:`backend.multifigure` control
4242
when the **MultiFigure** behaviour is desired.
4343

4444
**Note**
4545

4646
It is important to note, that the proposed solution, assumes that the
4747
[MEP22](https://github.com/matplotlib/matplotlib/wiki/Mep22) is
4848
already in place. This is simply because the actual implementation of
49-
the `Toolbar` makes it pretty hard to switch between canvases.
49+
the ``Toolbar`` makes it pretty hard to switch between canvases.
5050

5151
Implementation
5252
==============
5353

5454
The first implementation will be done in GTK3 using a Notebook as
5555
canvas container.
5656

57-
`.FigureManagerBase`
58-
--------------------
57+
``FigureManagerBase``
58+
---------------------
5959

6060
will add the following new methods
6161

62-
* `add_canvas`: To add a canvas to an existing `FigureManager` object
63-
* `remove_canvas`: To remove a canvas from a `FigureManager` object,
64-
if it is the last one, it will be destroyed
65-
* `move_canvas`: To move a canvas from one `FigureManager` to another.
66-
* `set_canvas_title`: To change the title associated with a specific
62+
* ``add_canvas``: To add a canvas to an existing
63+
`~.backend_template.FigureManager` object
64+
* ``remove_canvas``: To remove a canvas from a
65+
`~.backend_template.FigureManager` object, if it is the last one, it will be
66+
destroyed
67+
* ``move_canvas``: To move a canvas from one `~.backend_template.FigureManager`
68+
to another.
69+
* ``set_canvas_title``: To change the title associated with a specific
6770
canvas container
68-
* `get_canvas_title`: To get the title associated with a specific
71+
* ``get_canvas_title``: To get the title associated with a specific
6972
canvas container
70-
* `get_active_canvas`: To get the canvas that is in the foreground and
71-
is subject to the gui events. There is no `set_active_canvas`
72-
because the active canvas, is defined when `show` is called on a
73-
`Canvas` object.
73+
* ``get_active_canvas``: To get the canvas that is in the foreground and
74+
is subject to the gui events. There is no ``set_active_canvas``
75+
because the active canvas, is defined when ``show`` is called on a
76+
``Canvas`` object.
7477

75-
`new_figure_manager`
76-
--------------------
78+
``new_figure_manager``
79+
----------------------
7780

78-
To control which `FigureManager` will contain the new figures, an
79-
extra optional parameter *figuremanager* will be added, this parameter
80-
value will be passed to `new_figure_manager_given_figure`
81+
To control which `~.backend_template.FigureManager` will contain the new
82+
figures, an extra optional parameter *figuremanager* will be added, this
83+
parameter value will be passed to ``new_figure_manager_given_figure``.
8184

82-
`new_figure_manager_given_figure`
83-
---------------------------------
85+
``new_figure_manager_given_figure``
86+
-----------------------------------
8487

85-
* If *figuremanager* parameter is given, this `FigureManager` object
86-
will be used instead of creating a new one.
88+
* If *figuremanager* parameter is given, this
89+
`~.backend_template.FigureManager` object will be used instead of creating a
90+
new one.
8791
* If ``rcParams['backend.multifigure']`` is True: The last
88-
`FigureManager` object will be used instead of creating a new one.
92+
`~.backend_template.FigureManager` object will be used instead of creating a
93+
new one.
8994

90-
`NavigationBase`
91-
----------------
95+
``NavigationBase``
96+
------------------
9297

93-
Modifies the `NavigationBase` to keep a list of canvases, directing
94-
the actions to the active one
98+
Modifies the ``NavigationBase`` to keep a list of canvases, directing the
99+
actions to the active one.
95100

96101
Backward compatibility
97102
======================

‎doc/devel/MEP/MEP26.rst

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,14 +65,13 @@ The new methodology would require development of a number of steps:
6565
Implementation
6666
==============
6767

68-
It will be easiest to allow a '3rd party' to modify/set the style of
69-
an artist if the 'style' is created as a separate class and store
70-
against the artist as a property. The `.GraphicsContext` class already
71-
provides a the basis of a `Style` class and an artist's `~.Artist.draw` method can
72-
be refactored to use the `Style` class rather than setting up it's own
73-
`.GraphicsContext` and transferring it's style-related properties to
74-
it. A minimal example of how this could be implemented is shown here:
75-
https://github.com/JamesRamm/mpl_experiment
68+
It will be easiest to allow a '3rd party' to modify/set the style of an artist
69+
if the 'style' is created as a separate class and store against the artist as a
70+
property. The `.GraphicsContextBase` class already provides a the basis of a
71+
``Style`` class and an artist's `~.Artist.draw` method can be refactored to use
72+
the ``Style`` class rather than setting up its own `.GraphicsContextBase` and
73+
transferring its style-related properties to it. A minimal example of how this
74+
could be implemented is shown here: https://github.com/JamesRamm/mpl_experiment
7675

7776
IMO, this will also make the API and code base much neater as
7877
individual get/set methods for artist style properties are now

‎doc/devel/MEP/MEP29.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Using different size/color/family in a text annotation is difficult because the
2929
`~.Axes.text` method accepts argument for size/color/family/weight/etc. that are used
3030
for the whole text. But, if one wants, for example, to have different colors,
3131
one has to look at the gallery where one such example is provided:
32-
http://matplotlib.org/examples/text_labels_and_annotations/rainbow_text.html
32+
:doc:`/gallery/text_labels_and_annotations/rainbow_text`
3333

3434
This example takes a list of strings as well as a list of colors which makes it
3535
cumbersome to use. An alternative would be to use a restricted set of pango_-like markup and to interpret this markup.
@@ -59,8 +59,8 @@ Improvements
5959
Problems
6060
--------
6161

62-
* One serious problem is how to deal with text having both latex and
63-
html-like tags. For example, consider the following::
62+
* One serious problem is how to deal with text having both LaTeX and
63+
HTML-like tags. For example, consider the following::
6464

6565
$<b>Bold$</b>
6666

0 commit comments

Comments
 (0)