Skip to content

DOC : whole bunch of documentation clean up #3170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 20 commits into from
Closed

DOC : whole bunch of documentation clean up #3170

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
a727bdc
STY : minor rst formatting
tacaswell Jun 29, 2014
9e1c9cf
DOC : removed old movie example from FAQ
tacaswell Jun 29, 2014
5f60a1e
DOC : re-worked patch/bug report FAQ
tacaswell Jun 30, 2014
0c85dfe
DOC : removed reference to making a flash backend
tacaswell Jun 30, 2014
050f3af
DOC : minor tweaks to coding_guide
tacaswell Jun 30, 2014
6cfccbf
DOC : minor changes to docs
tacaswell Jun 30, 2014
284135e
DOC : major work to development workflow docs
tacaswell Jun 30, 2014
d11fc1a
DOC : tweaked FAQ about new features
tacaswell Jul 2, 2014
9aa5f70
DOC : added figure part diagram
tacaswell Jul 3, 2014
81e963b
DOC : grammer fixes and doc edits
tacaswell Jul 4, 2014
23a63da
DOC : minor punctuation change
tacaswell Jul 4, 2014
b1f0a60
DOC : removed reference to pylab on the front page
tacaswell Jul 6, 2014
b21e34d
DOC : minor edits
tacaswell Jul 12, 2014
5b613d4
DOC : killed tabs with fire
tacaswell Jul 12, 2014
ed65167
DOC : changes to testing docs
tacaswell Jul 12, 2014
6d0503b
DOC : minor rst markup fix
tacaswell Jul 13, 2014
a9b25e1
DOC : fix typo
tacaswell Jul 13, 2014
6fcd723
DOC : minor indentation fix
tacaswell Jul 18, 2014
a26114d
DOC : capitalization change
tacaswell Jul 18, 2014
19e8ad1
DOC : edits from efiring
tacaswell Jul 18, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
DOC : added figure part diagram 
Added map of major parts of a figure
  • Loading branch information
@tacaswell
tacaswell committed Jul 18, 2014
commit 9aa5f706bca6cf908e12d60d6bd70555bdbf06eb
Binary file added doc/faq/fig_map.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
69 changes: 69 additions & 0 deletions doc/faq/usage_faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,75 @@ For even more control -- which is essential for things like embedding
matplotlib plots in GUI applications -- the pyplot level may be dropped
completely, leaving a purely object-oriented approach.

.. _figure_parts:
Copy link
Member

Choose a reason for hiding this comment

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

Generally I agree with the need for this document, but I'm not 100% comfortable with the approach taken. It might be worth getting a novice onboard to help get some coherent structure to the way things are introduced.

Copy link
Member Author

Choose a reason for hiding this comment

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

I started at the outside and worked my way in. Even if this is not perfect, we need to have this marked up figure someplace in the docs.


Parts of a Figure
=================
.. image:: fig_map.png

:class:`~matplotlib.figure.Figure`
----------------------------------

The _whole_ figure (marked as the outer red box). The figure keeps
Copy link
Member

Choose a reason for hiding this comment

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

I'd like to be a little more positive with this whole paragraph. Maybe we can talk during the scipy sprint.

Copy link
Member Author

Choose a reason for hiding this comment

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

What do you mean by positive?

track of all the child :class:`~matplotlib.axes.Axes`, a smattering of
'special' artists (titles, figure legends, etc), and the **canvas**.
(Don't worry too much about the canvas, it is crucial as it is the
object that actually does the drawing to get you your plot, but as the
user it is more-or-less invisible to you). A figure can have any
number of :class:`~matplotlib.axes.Axes`, but to be useful should have
at least one.

The easiest way to create a new figure is with pyplot::

fig = plt.figure() # an empty figure with no axes
fig, ax_lst = plt.subplots(2, 2) # a figure with a 2x2 grid of Axes


:class:`~matplotlib.axes.Axes`
------------------------------

This is what you think of as 'a plot', it is the region of the image
with the data space (marked as the inner blue box). A given figure
can contain many Axes, but a given :class:`~matplotlib.axes.Axes`
object can only be in one :class:`~matplotlib.figure.Figure`. The
axes contains two (or three in the case of 3D)
Copy link
Member

Choose a reason for hiding this comment

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

Capitalize "Axes" here for consistency?

Copy link
Member Author

Choose a reason for hiding this comment

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

Fixed, I should probably squash all of these commits down.

:class:`~matplotlib.axis.Axis` objects (be aware of the difference
between **Axes** and **Axis**) which take care of the data limits (the
data limits can also be controlled via set via the
:func:`~matplotlib.axes.Axes.set_xlim` and
:func:`~matplotlib.axes.Axes.set_ylim` member :class:`Axes` member
Copy link
Member

Choose a reason for hiding this comment

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

"member Axes member functions.". It'd be good to make this more pythonic.

Copy link
Member Author

Choose a reason for hiding this comment

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

copy and paste text editing!

functions). Each :class:`Axes` has a title (set via
:func:`~matplotlib.axes.Axes.set_title`), an x-label (set via
:func:`~matplotlib.axes.Axes.set_xlabel`), and a y-label set via
:func:`~matplotlib.axes.Axes.set_ylabel`).

The :class:`Axes` class and it's member functions are the primary entry
point to working with the OO interface.

:class:`~matplotlib.axis.Axis`
------------------------------

These are the number line like objects (circled in green). They take
Copy link
Member

Choose a reason for hiding this comment

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

Hyphenate, "number-line-like".

care of setting the graph limits and generating the ticks (the marks
on the axis) and ticklabels (strings labeling the ticks). The
location of the ticks is determined by a
:class:`~matplotlib.ticker.Locator` object and the ticklabel strings
are formatted by a :class:`~matplotlib.ticker.Formatter`. The
combination of the correct :class:`Locator` and :class:`Formatter` gives
very fine control over the tick labels.
Copy link
Member

Choose a reason for hiding this comment

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

-> "tick locations and labels"


:class:`~matplotlib.artist.Artist`
----------------------------------

Basically everything you can see on the figure is an artist (even the
:class:`Figure`, :class:`Axes`, and :class:`Axis` objects). This
includes :class:`Text` objects, :class:`Line2D` objects,
:class:`collection` objects, :class:`Patch` objects ... (you get the idea).
When the figure is rendered, all of the artists are drawn
(recursively) to the **canvas**. A given artist can only be in one
Copy link
Member

Choose a reason for hiding this comment

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

Delete the "(recursively)". I know what you mean, but this is not quite the right way to say it, and it doesn't need to be said here anyway. Also, suggested to replace "A given artist...":
"Most Artists are tied to an Axes; such an Artist cannot be shared by multiple Axes, or moved from one to another."

`Axes`.


.. _pylab:

Matplotlib, pyplot and pylab: how are they related?
Expand Down