From 46a83498a8337a4fb179a40e5ba40a2a6e973911 Mon Sep 17 00:00:00 2001 From: Christopher Holdgraf Date: Thu, 4 May 2017 12:39:48 -0700 Subject: [PATCH 1/5] SG for toolkits --- doc/_templates/automodule.rst | 32 +-- doc/api/index.rst | 10 + doc/api/toolkits/axes_grid.rst | 21 ++ doc/api/toolkits/mplot3d.rst | 126 +++++++++++ doc/conf.py | 28 +-- doc/make.py | 42 +--- .../axes_grid1/api/anchored_artists_api.rst | 7 - .../axes_grid1/api/axes_divider_api.rst | 18 -- .../axes_grid1/api/axes_grid_api.rst | 11 - .../axes_grid1/api/axes_size_api.rst | 5 - doc/mpl_toolkits/axes_grid1/api/index.rst | 16 -- .../axes_grid1/api/inset_locator_api.rst | 7 - doc/mpl_toolkits/axes_grid1/examples | 1 - doc/mpl_toolkits/axes_grid1/index.rst | 9 +- .../axes_grid1/users/axes_divider.rst | 103 --------- doc/mpl_toolkits/axes_grid1/users/index.rst | 12 - .../axisartist/api/axis_artist_api.rst | 16 -- doc/mpl_toolkits/axisartist/api/index.rst | 12 - doc/mpl_toolkits/axisartist/examples | 1 - doc/mpl_toolkits/axisartist/index.rst | 12 +- doc/mpl_toolkits/axisartist/overview.rst | 153 ------------- doc/mpl_toolkits/axisartist/users/index.rst | 12 - doc/mpl_toolkits/index.rst | 45 ++-- doc/mpl_toolkits/mplot3d/api.rst | 64 ------ doc/mpl_toolkits/mplot3d/index.rst | 5 +- doc/users/prev_whats_new/whats_new_1.1.rst | 2 +- lib/mpl_toolkits/axisartist/axislines.py | 4 +- .../axisartist/grid_helper_curvelinear.py | 5 +- lib/mpl_toolkits/mplot3d/axes3d.py | 13 +- tutorials/toolkits/README.txt | 7 + .../toolkits/axes_grid.py | 127 +++++++++-- .../toolkits/axisartist.py | 205 +++++++++++++++--- .../toolkits/mplot3d.py | 39 ++-- 33 files changed, 521 insertions(+), 649 deletions(-) create mode 100644 doc/api/toolkits/axes_grid.rst create mode 100644 doc/api/toolkits/mplot3d.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/api/anchored_artists_api.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/api/axes_divider_api.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/api/axes_grid_api.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/api/axes_size_api.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/api/index.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/api/inset_locator_api.rst delete mode 120000 doc/mpl_toolkits/axes_grid1/examples delete mode 100644 doc/mpl_toolkits/axes_grid1/users/axes_divider.rst delete mode 100644 doc/mpl_toolkits/axes_grid1/users/index.rst delete mode 100644 doc/mpl_toolkits/axisartist/api/axis_artist_api.rst delete mode 100644 doc/mpl_toolkits/axisartist/api/index.rst delete mode 120000 doc/mpl_toolkits/axisartist/examples delete mode 100644 doc/mpl_toolkits/axisartist/overview.rst delete mode 100644 doc/mpl_toolkits/axisartist/users/index.rst delete mode 100644 doc/mpl_toolkits/mplot3d/api.rst create mode 100644 tutorials/toolkits/README.txt rename doc/mpl_toolkits/axes_grid1/overview.rst => tutorials/toolkits/axes_grid.py (77%) rename doc/mpl_toolkits/axisartist/users/axisartist.rst => tutorials/toolkits/axisartist.py (72%) rename doc/mpl_toolkits/mplot3d/tutorial.rst => tutorials/toolkits/mplot3d.py (95%) diff --git a/doc/_templates/automodule.rst b/doc/_templates/automodule.rst index 9e50ee465090..7fa0780eb266 100644 --- a/doc/_templates/automodule.rst +++ b/doc/_templates/automodule.rst @@ -5,8 +5,8 @@ :no-members: :no-inherited-members: -{% block functions %} -{% if functions %} +{% block classes %} +{% if classes %} Classes ------- @@ -14,15 +14,13 @@ Classes .. autosummary:: :template: autosummary.rst :toctree: - -{% for item in classes %} - {{ item }} -{% endfor %} +{% for item in classes %}{% if item not in ['zip', 'map', 'reduce'] %} + {{ item }}{% endif %}{% endfor %} {% endif %} {% endblock %} -{% block exceptions %} -{% if exceptions %} +{% block functions %} +{% if functions %} Functions --------- @@ -31,21 +29,7 @@ Functions :template: autosummary.rst :toctree: -{% for item in functions %} - {{ item }} -{% endfor %} +{% for item in functions %}{% if item not in ['zip', 'map', 'reduce'] %} + {{ item }}{% endif %}{% endfor %} {% endif %} {% endblock %} - -{% block classes %} -{% if classes %} - -Exceptions ----------- - -.. autosummary:: -{% for item in exceptions %} - {{ item }} -{%- endfor %} -{% endif %} -{% endblock %} \ No newline at end of file diff --git a/doc/api/index.rst b/doc/api/index.rst index 70a4f47c3576..b44c388607b2 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -65,3 +65,13 @@ :template: autofunctions.rst pyplot + + +Toolkits +-------- + +.. toctree:: + :maxdepth: 1 + + toolkits/axes_grid.rst + toolkits/mplot3d.rst diff --git a/doc/api/toolkits/axes_grid.rst b/doc/api/toolkits/axes_grid.rst new file mode 100644 index 000000000000..e70d57de3a60 --- /dev/null +++ b/doc/api/toolkits/axes_grid.rst @@ -0,0 +1,21 @@ +.. _axes_grid-api-index: + +#################################### +The Matplotlib axes_grid Toolkit API +#################################### + +:Release: |version| +:Date: |today| + +.. currentmodule:: mpl_toolkits + +Axes Grid +--------- + +.. autosummary:: + :toctree: ../_as_gen + :template: automodule.rst + + axes_grid + axes_grid1 + axisartist diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst new file mode 100644 index 000000000000..a0355207cb66 --- /dev/null +++ b/doc/api/toolkits/mplot3d.rst @@ -0,0 +1,126 @@ +.. _toolkit_mplot3d-api: + +*********** +mplot3d API +*********** + +.. contents:: + :backlinks: none + +.. currentmodule:: mpl_toolkits.mplot3d + +.. _toolkit_mplot3d-axesapi: + +:mod:`~mpl_toolkits.mplot3d.axes3d` +=================================== + +.. note:: + Significant effort went into bringing axes3d to feature-parity with + regular axes objects for version 1.1.0. However, more work remains. + Please report any functions that do not behave as expected as a bug. + In addition, help and patches would be greatly appreciated! + +.. autosummary:: + :toctree: ../_as_gen + :template: autosummary.rst + + axes3d.Axes + axes3d.Axes3D + axes3d.Bbox + axes3d.LightSource + axes3d.Normalize + axes3d.Triangulation + + +.. _toolkit_mplot3d-axisapi: + +:mod:`~mpl_toolkits.mplot3d.axis3d` +=================================== + +.. note:: + Historically, axis3d has suffered from having hard-coded constants + controlling the look and feel of the 3D plot. This precluded user + level adjustments such as label spacing, font colors and panel colors. + For version 1.1.0, these constants have been consolidated into a single + private member dictionary, `self._axinfo`, for the axis object. This is + intended only as a stop-gap measure to allow user-level customization, + but it is not intended to be permanent. + +.. autosummary:: + :toctree: ../_as_gen + :template: autosummary.rst + + axis3d.Axis + axis3d.XAxis + axis3d.YAxis + axis3d.ZAxis + axis3d.get_flip_min_max + axis3d.move_from_center + axis3d.tick_update_position + + +.. _toolkit_mplot3d-artapi: + +:mod:`~mpl_toolkits.mplot3d.art3d` +================================== + +.. autosummary:: + :toctree: ../_as_gen + :template: autosummary.rst + + art3d.Line3D + art3d.Line3DCollection + art3d.Patch3D + art3d.Patch3DCollection + art3d.Path3DCollection + art3d.PathPatch3D + art3d.Poly3DCollection + art3d.Text3D + art3d.get_colors + art3d.get_dir_vector + art3d.get_patch_verts + art3d.iscolor + art3d.juggle_axes + art3d.line_2d_to_3d + art3d.line_collection_2d_to_3d + art3d.norm_angle + art3d.norm_text_angle + art3d.patch_2d_to_3d + art3d.patch_collection_2d_to_3d + art3d.path_to_3d_segment + art3d.path_to_3d_segment_with_codes + art3d.pathpatch_2d_to_3d + art3d.paths_to_3d_segments + art3d.paths_to_3d_segments_with_codes + art3d.poly_collection_2d_to_3d + art3d.rotate_axes + art3d.text_2d_to_3d + art3d.zalpha + +.. _toolkit_mplot3d-projapi: + +:mod:`~mpl_toolkits.mplot3d.proj3d` +=================================== + +.. autosummary:: + :toctree: ../_as_gen + :template: autosummary.rst + + proj3d.inv_transform + proj3d.line2d + proj3d.line2d_dist + proj3d.line2d_seg_dist + proj3d.mod + proj3d.persp_transformation + proj3d.proj_points + proj3d.proj_trans_clip_points + proj3d.proj_trans_points + proj3d.proj_transform + proj3d.proj_transform_clip + proj3d.proj_transform_vec + proj3d.proj_transform_vec_clip + proj3d.rot_x + proj3d.transform + proj3d.vec_pad_ones + proj3d.view_transformation + proj3d.world_transformation diff --git a/doc/conf.py b/doc/conf.py index 5e5dba666a17..422d33374c0c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -101,7 +101,7 @@ def _check_deps(): 'examples_dirs': ['../examples', '../tutorials'], 'filename_pattern': '^((?!sgskip).)*$', 'gallery_dirs': ['gallery', 'tutorials'], - 'doc_module': ('matplotlib',), + 'doc_module': ('matplotlib', 'mpl_toolkits'), 'reference_url': {'matplotlib': None, 'numpy': 'http://docs.scipy.org/doc/numpy/reference', 'scipy': 'http://docs.scipy.org/doc/scipy/reference'}, @@ -167,32 +167,6 @@ def _check_deps(): plot_formats = [('png', 100), ('pdf', 100)] -# Subdirectories in 'examples/' directory of package and titles for gallery -mpl_example_sections = [ - ('lines_bars_and_markers', 'Lines, bars, and markers'), - ('shapes_and_collections', 'Shapes and collections'), - ('statistics', 'Statistical plots'), - ('images_contours_and_fields', 'Images, contours, and fields'), - ('pie_and_polar_charts', 'Pie and polar charts'), - ('color', 'Color'), - ('text_labels_and_annotations', 'Text, labels, and annotations'), - ('ticks_and_spines', 'Ticks and spines'), - ('scales', 'Axis scales'), - ('subplots_axes_and_figures', 'Subplots, axes, and figures'), - ('style_sheets', 'Style sheets'), - ('specialty_plots', 'Specialty plots'), - ('showcase', 'Showcase'), - ('api', 'API'), - ('pylab_examples', 'pylab examples'), - ('mplot3d', 'mplot3d toolkit'), - ('axes_grid1', 'axes_grid1 toolkit'), - ('axisartist', 'axisartist toolkit'), - ('units', 'units'), - ('widgets', 'widgets'), - ('misc', 'Miscellaneous examples'), - ] - - # Github extension github_project_url = "https://github.com/matplotlib/matplotlib/" diff --git a/doc/make.py b/doc/make.py index e4fead0beeed..ac83d1b1d683 100755 --- a/doc/make.py +++ b/doc/make.py @@ -202,12 +202,8 @@ def clean(): """Remove generated files. """ shutil.rmtree("build", ignore_errors=True) shutil.rmtree("examples", ignore_errors=True) - for pattern in ['mpl_examples/api/*.png', - 'mpl_examples/pylab_examples/*.png', - 'mpl_examples/pylab_examples/*.pdf', - 'mpl_examples/units/*.png', - 'mpl_examples/pyplots/tex_demo.png', - '_static/matplotlibrc', + shutil.rmtree("api/_as_gen", ignore_errors=True) + for pattern in ['_static/matplotlibrc', '_templates/gallery.html', 'users/installing.rst']: for filename in glob.glob(pattern): @@ -247,40 +243,6 @@ def build_all(): os.chdir(os.path.dirname(os.path.join(current_dir, __file__))) copy_if_out_of_date('../INSTALL.rst', 'users/installing.rst') -# Create the examples symlink, if it doesn't exist - -required_symlinks = [ - ('mpl_examples', '../examples/'), - ('mpl_toolkits/axes_grid1/examples', '../../../examples/axes_grid1/'), - ('mpl_toolkits/axisartist/examples', '../../../examples/axisartist/') - ] - -symlink_warnings = [] -for link, target in required_symlinks: - if sys.platform == 'win32' and os.path.isfile(link): - # This is special processing that applies on platforms that don't deal - # with git symlinks -- probably only MS windows. - delete = False - with open(link, 'r') as link_content: - delete = target == link_content.read() - if delete: - symlink_warnings.append('deleted: doc/{0}'.format(link)) - os.unlink(link) - else: - raise RuntimeError("doc/{0} should be a directory or symlink -- it" - " isn't".format(link)) - if not os.path.exists(link): - try: - os.symlink(os.path.normcase(target), link) - except OSError: - symlink_warnings.append('files copied to {0}'.format(link)) - shutil.copytree(os.path.join(link, '..', target), link) - -if sys.platform == 'win32' and len(symlink_warnings) > 0: - print('The following items related to symlinks will show up ' - 'as spurious changes in your \'git status\':\n\t{0}' - .format('\n\t'.join(symlink_warnings))) - parser = argparse.ArgumentParser(description='Build matplotlib docs') parser.add_argument("cmd", help=("Command to execute. Can be multiple. " "Valid options are: %s" % (funcd.keys())), nargs='*') diff --git a/doc/mpl_toolkits/axes_grid1/api/anchored_artists_api.rst b/doc/mpl_toolkits/axes_grid1/api/anchored_artists_api.rst deleted file mode 100644 index 4aeba4e3aaf6..000000000000 --- a/doc/mpl_toolkits/axes_grid1/api/anchored_artists_api.rst +++ /dev/null @@ -1,7 +0,0 @@ -:mod:`mpl_toolkits.axes_grid1.anchored_artists` -=============================================== - -.. automodule:: mpl_toolkits.axes_grid1.anchored_artists - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/mpl_toolkits/axes_grid1/api/axes_divider_api.rst b/doc/mpl_toolkits/axes_grid1/api/axes_divider_api.rst deleted file mode 100644 index df3610d680ed..000000000000 --- a/doc/mpl_toolkits/axes_grid1/api/axes_divider_api.rst +++ /dev/null @@ -1,18 +0,0 @@ - -:mod:`mpl_toolkits.axes_grid1.axes_divider` -=========================================== - -.. autoclass:: mpl_toolkits.axes_grid1.axes_divider.Divider - :members: - :undoc-members: - - -.. autoclass:: mpl_toolkits.axes_grid1.axes_divider.AxesLocator - :members: - :undoc-members: - -.. autoclass:: mpl_toolkits.axes_grid1.axes_divider.SubplotDivider - :members: - -.. autoclass:: mpl_toolkits.axes_grid1.axes_divider.AxesDivider - :members: diff --git a/doc/mpl_toolkits/axes_grid1/api/axes_grid_api.rst b/doc/mpl_toolkits/axes_grid1/api/axes_grid_api.rst deleted file mode 100644 index c52efc8ff102..000000000000 --- a/doc/mpl_toolkits/axes_grid1/api/axes_grid_api.rst +++ /dev/null @@ -1,11 +0,0 @@ - -:mod:`mpl_toolkits.axes_grid1.axes_grid` -======================================== - -.. autoclass:: mpl_toolkits.axes_grid1.axes_grid.Grid - :members: - :undoc-members: - -.. autoclass:: mpl_toolkits.axes_grid1.axes_grid.ImageGrid - :members: - :undoc-members: diff --git a/doc/mpl_toolkits/axes_grid1/api/axes_size_api.rst b/doc/mpl_toolkits/axes_grid1/api/axes_size_api.rst deleted file mode 100644 index 06a0b053a9f2..000000000000 --- a/doc/mpl_toolkits/axes_grid1/api/axes_size_api.rst +++ /dev/null @@ -1,5 +0,0 @@ -:mod:`mpl_toolkits.axes_grid1.axes_size` -======================================== - -.. automodule:: mpl_toolkits.axes_grid1.axes_size - :members: Fixed, Scaled, AxesX, AxesY, MaxWidth, MaxHeight, Fraction, Padded, from_any diff --git a/doc/mpl_toolkits/axes_grid1/api/index.rst b/doc/mpl_toolkits/axes_grid1/api/index.rst deleted file mode 100644 index 8a83b03f708e..000000000000 --- a/doc/mpl_toolkits/axes_grid1/api/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _axes_grid1-api-index: - -####################################### - The Matplotlib axes_grid1 Toolkit API -####################################### - -:Release: |version| -:Date: |today| - -.. toctree:: - - anchored_artists_api.rst - axes_size_api.rst - axes_divider_api.rst - axes_grid_api.rst - inset_locator_api.rst diff --git a/doc/mpl_toolkits/axes_grid1/api/inset_locator_api.rst b/doc/mpl_toolkits/axes_grid1/api/inset_locator_api.rst deleted file mode 100644 index c9c1bfbbb49c..000000000000 --- a/doc/mpl_toolkits/axes_grid1/api/inset_locator_api.rst +++ /dev/null @@ -1,7 +0,0 @@ -:mod:`mpl_toolkits.axes_grid1.inset_locator` -============================================ - -.. automodule:: mpl_toolkits.axes_grid1.inset_locator - :members: - :undoc-members: - :show-inheritance: diff --git a/doc/mpl_toolkits/axes_grid1/examples b/doc/mpl_toolkits/axes_grid1/examples deleted file mode 120000 index 4a4be2d52c98..000000000000 --- a/doc/mpl_toolkits/axes_grid1/examples +++ /dev/null @@ -1 +0,0 @@ -../../../examples/axes_grid1/ \ No newline at end of file diff --git a/doc/mpl_toolkits/axes_grid1/index.rst b/doc/mpl_toolkits/axes_grid1/index.rst index 1f758d12bc36..aacb1cc5b872 100644 --- a/doc/mpl_toolkits/axes_grid1/index.rst +++ b/doc/mpl_toolkits/axes_grid1/index.rst @@ -10,6 +10,8 @@ aspect parameter in matplotlib adjust the position of the single axes, axesgrid1 toolkit provides a framework to adjust the position of multiple axes according to their aspects. +See :ref:`axes_grid1_users-guide-index` for a guide on the usage of axes_grid1. + .. image:: ../../_static/demo_axes_grid.png @@ -20,10 +22,3 @@ multiple axes according to their aspects. has divided into two separate namespace (*axes_grid1* and *axisartist*). While *axes_grid* namespace is maintained for the backward compatibility, use of *axes_grid1* and *axisartist* is recommended. - -.. toctree:: - :maxdepth: 2 - - overview.rst - users/index.rst - api/index.rst diff --git a/doc/mpl_toolkits/axes_grid1/users/axes_divider.rst b/doc/mpl_toolkits/axes_grid1/users/axes_divider.rst deleted file mode 100644 index 17eebc300fc8..000000000000 --- a/doc/mpl_toolkits/axes_grid1/users/axes_divider.rst +++ /dev/null @@ -1,103 +0,0 @@ -AxesDivider -=========== - -The axes_divider module provide helper classes to adjust the axes -positions of set of images in the drawing time. - -* :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a classes of - units that the size of each axes will be determined. For example, - you can specify a fixed size - -* :class:`~mpl_toolkits.axes_grid1.axes_size.Divider` this is the class - that is used calculates the axes position. It divides the given - rectangular area into several areas. You initialize the divider by - setting the horizontal and vertical list of sizes that the division - will be based on. You then use the new_locator method, whose return - value is a callable object that can be used to set the axes_locator - of the axes. - - -You first initialize the divider by specifying its grids, i.e., -horizontal and vertical. - -for example,:: - - rect = [0.2, 0.2, 0.6, 0.6] - horiz=[h0, h1, h2, h3] - vert=[v0, v1, v2] - divider = Divider(fig, rect, horiz, vert) - -where, rect is a bounds of the box that will be divided and h0,..h3, -v0,..v2 need to be an instance of classes in the -:mod:`~mpl_toolkits.axes_grid1.axes_size`. They have *get_size* method -that returns a tuple of two floats. The first float is the relative -size, and the second float is the absolute size. Consider a following -grid. - -+-----+-----+-----+-----+ -| v0 | | | | -+-----+-----+-----+-----+ -| v1 | | | | -+-----+-----+-----+-----+ -|h0,v2| h1 | h2 | h3 | -+-----+-----+-----+-----+ - - -* v0 => 0, 2 -* v1 => 2, 0 -* v2 => 3, 0 - -The height of the bottom row is always 2 (axes_divider internally -assumes that the unit is inch). The first and the second rows with -height ratio of 2:3. For example, if the total height of the grid 6, -then the first and second row will each occupy 2/(2+3) and 3/(2+3) of -(6-1) inches. The widths of columns (horiz) will be similarly -determined. When aspect ratio is set, the total height (or width) will -be adjusted accordingly. - - -The :mod:`mpl_toolkits.axes_grid1.axes_size` contains several classes -that can be used to set the horizontal and vertical configurations. For -example, for the vertical configuration above will be:: - - from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled - vert = [Fixed(2), Scaled(2), Scaled(3)] - -After you set up the divider object, then you create a locator -instance which will be given to the axes.:: - - locator = divider.new_locator(nx=0, ny=1) - ax.set_axes_locator(locator) - -The return value of the new_locator method is a instance of the -AxesLocator class. It is a callable object that returns the -location and size of the cell at the first column and the second row. -You may create a locator that spans over multiple cells.:: - - locator = divider.new_locator(nx=0, nx=2, ny=1) - -The above locator, when called, will return the position and size of -the cells spanning the first and second column and the first row. You -may consider it as [0:2, 1]. - -See the example, - -.. figure:: ../../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider2_001.png - :target: ../../../gallery/axes_grid1/simple_axes_divider2.html - :align: center - :scale: 50 - - Simple Axes Divider2 - -You can adjust the size of the each axes according to their x or y -data limits (AxesX and AxesY), similar to the axes aspect parameter. - -.. figure:: ../../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png - :target: ../../../gallery/axes_grid1/simple_axes_divider3.html - :align: center - :scale: 50 - - Simple Axes Divider3 - - - diff --git a/doc/mpl_toolkits/axes_grid1/users/index.rst b/doc/mpl_toolkits/axes_grid1/users/index.rst deleted file mode 100644 index 9251b9298a73..000000000000 --- a/doc/mpl_toolkits/axes_grid1/users/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _axes_grid1_users-guide-index: - -################################################# - The Matplotlib axes_grid1 Toolkit User's Guide -################################################# - -:Release: |version| -:Date: |today| - -.. toctree:: - - axes_divider.rst diff --git a/doc/mpl_toolkits/axisartist/api/axis_artist_api.rst b/doc/mpl_toolkits/axisartist/api/axis_artist_api.rst deleted file mode 100644 index e8705fc01b45..000000000000 --- a/doc/mpl_toolkits/axisartist/api/axis_artist_api.rst +++ /dev/null @@ -1,16 +0,0 @@ - -:mod:`mpl_toolkits.axisartist.axis_artist` -========================================== - -.. autoclass:: mpl_toolkits.axisartist.axis_artist.AxisArtist - :members: - :undoc-members: - -.. autoclass:: mpl_toolkits.axisartist.axis_artist.Ticks - :members: - -.. autoclass:: mpl_toolkits.axisartist.axis_artist.AxisLabel - :members: - -.. autoclass:: mpl_toolkits.axisartist.axis_artist.TickLabels - :members: diff --git a/doc/mpl_toolkits/axisartist/api/index.rst b/doc/mpl_toolkits/axisartist/api/index.rst deleted file mode 100644 index 069d82bc7c29..000000000000 --- a/doc/mpl_toolkits/axisartist/api/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _axisartist-api-index: - -####################################### - The Matplotlib axisartist Toolkit API -####################################### - -:Release: |version| -:Date: |today| - -.. toctree:: - - axis_artist_api.rst diff --git a/doc/mpl_toolkits/axisartist/examples b/doc/mpl_toolkits/axisartist/examples deleted file mode 120000 index bd4a984623a0..000000000000 --- a/doc/mpl_toolkits/axisartist/examples +++ /dev/null @@ -1 +0,0 @@ -../../../examples/axisartist/ \ No newline at end of file diff --git a/doc/mpl_toolkits/axisartist/index.rst b/doc/mpl_toolkits/axisartist/index.rst index 22855f1f2cdd..4bb80df51fee 100644 --- a/doc/mpl_toolkits/axisartist/index.rst +++ b/doc/mpl_toolkits/axisartist/index.rst @@ -3,9 +3,11 @@ Matplotlib axisartist Toolkit ============================= -.. toctree:: - :maxdepth: 2 +The *axisartist* namespace includes a derived Axes implementation. The +biggest difference is that the artists responsible to draw axis line, +ticks, ticklabel and axis labels are separated out from the mpl's Axis +class, which are much more than artists in the original mpl. This +change was strongly motivated to support curvilinear grid. - overview.rst - users/index.rst - api/index.rst +You can find a tutorial describing usage of axisartist at +:ref:`axisartist_users-guide-index`. diff --git a/doc/mpl_toolkits/axisartist/overview.rst b/doc/mpl_toolkits/axisartist/overview.rst deleted file mode 100644 index 80ad27d041bf..000000000000 --- a/doc/mpl_toolkits/axisartist/overview.rst +++ /dev/null @@ -1,153 +0,0 @@ -============================== -Overview of axisartist toolkit -============================== - -.. warning:: - *axisartist* uses a custom Axes class - (derived from the mpl's original Axes class). - As a side effect, some commands (mostly tick-related) do not work. - - -The *axisartist* contains custom Axes class that is meant to support for -curvilinear grids (e.g., the world coordinate system in astronomy). -Unlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis -to draw ticks, ticklines and etc., Axes in axisartist uses special -artist (AxisArtist) which can handle tick, ticklines and etc. for -curved coordinate systems. - -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png - :target: ../../gallery/axisartist/demo_floating_axis.html - :align: center - :scale: 50 - - Demo Floating Axis - -Since it uses special artists, some mpl commands that work on -Axes.xaxis and Axes.yaxis may not work. - -axisartist ----------- - -*axisartist* module provides a custom (and very experimental) Axes -class, where each axis (left, right, top and bottom) have a separate -associated artist which is responsible to draw axis-line, ticks, -ticklabels, label. Also, you can create your own axis, which can pass -through a fixed position in the axes coordinate, or a fixed position -in the data coordinate (i.e., the axis floats around when viewlimit -changes). - -The axes class, by default, has its xaxis and yaxis invisible, and -has 4 additional artists which are responsible for drawing the 4 axis sides in -"left","right","bottom" and "top". They are accessed as -ax.axis["left"], ax.axis["right"], and so on, i.e., ax.axis is a -dictionary that contains artists (note that ax.axis is still a -callable methods and it behaves as an original Axes.axis method in -mpl). - -To create an axes, :: - - import mpl_toolkits.axisartist as AA - fig = plt.figure(1) - ax = AA.Axes(fig, [0.1, 0.1, 0.8, 0.8]) - fig.add_axes(ax) - -or to create a subplot :: - - ax = AA.Subplot(fig, 111) - fig.add_subplot(ax) - -For example, you can hide the right, and top axis by :: - - ax.axis["right"].set_visible(False) - ax.axis["top"].set_visible(False) - - -.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axisline3_001.png - :target: ../../gallery/userdemo/simple_axisline3.html - :align: center - :scale: 50 - - Simple Axisline3 - - -It is also possible to add an extra axis. For example, you may have an -horizontal axis at y=0 (in data coordinate). :: - - ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0) - -.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axisartist1_001.png - :target: ../../gallery/userdemo/simple_axisartist1.html - :align: center - :scale: 50 - - Simple Axisartist1 - - -Or a fixed axis with some offset :: - - # make new (right-side) yaxis, but wth some offset - ax.axis["right2"] = ax.new_fixed_axis(loc="right", - offset=(20, 0)) - - - -axisartist with ParasiteAxes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Most commands in the axes_grid1 toolkit can take a axes_class keyword -argument, and the commands creates an axes of the given class. For example, -to create a host subplot with axisartist.Axes, :: - - import mpl_toolkits.axisartist as AA - from mpl_toolkits.axes_grid1 import host_subplot - - host = host_subplot(111, axes_class=AA.Axes) - - -Here is an example that uses parasiteAxes. - - -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png - :target: ../../gallery/axisartist/demo_parasite_axes2.html - :align: center - :scale: 50 - - Demo Parasite Axes2 - - - -Curvilinear Grid ----------------- - -The motivation behind the AxisArtist module is to support curvilinear grid -and ticks. - -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png - :target: ../../gallery/axisartist/demo_curvelinear_grid.html - :align: center - :scale: 50 - - Demo Curvelinear Grid - -See :ref:`axisartist-manual` for more details. - - -Floating Axes -------------- - -This also support a Floating Axes whose outer axis are defined as -floating axis. - -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png - :target: ../../gallery/axisartist/demo_floating_axes.html - :align: center - :scale: 50 - - Demo Floating Axes - - - - - - - diff --git a/doc/mpl_toolkits/axisartist/users/index.rst b/doc/mpl_toolkits/axisartist/users/index.rst deleted file mode 100644 index 88f452378981..000000000000 --- a/doc/mpl_toolkits/axisartist/users/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _axisartist_users-guide-index: - -################################################ - The Matplotlib axisartist Toolkit User's Guide -################################################ - -:Release: |version| -:Date: |today| - -.. toctree:: - - axisartist.rst diff --git a/doc/mpl_toolkits/index.rst b/doc/mpl_toolkits/index.rst index e36f1b030e68..ba9f3337627d 100644 --- a/doc/mpl_toolkits/index.rst +++ b/doc/mpl_toolkits/index.rst @@ -1,12 +1,5 @@ .. _toolkits-index: -.. toctree:: - :hidden: - - axes_grid1/index.rst - axisartist/index.rst - mplot3d/index.rst - .. _toolkits: ######## @@ -24,11 +17,12 @@ Matplotlib. mplot3d ======= - -:ref:`mpl_toolkits.mplot3d ` provides some basic 3D +:mod:`mpl_toolkits.mplot3d` provides some basic 3D plotting (scatter, surf, line, mesh) tools. Not the fastest or feature complete 3D library out there, but ships with Matplotlib and thus may be a -lighter weight solution for some use cases. +lighter weight solution for some use cases. Check out the +:ref:`mplot3d tutorial ` for more +information. .. figure:: ../gallery/mplot3d/images/sphx_glr_contourf3d_2_001.png :target: ../gallery/mplot3d/contourf3d_2.html @@ -37,18 +31,30 @@ lighter weight solution for some use cases. Contourf3d 2 +.. toctree:: + :maxdepth: 2 + + mplot3d/index.rst + mplot3d/faq.rst + +Links +----- +* mpl3d API: :ref:`toolkit_mplot3d-api` + .. _toolkit_axes_grid1: axes_grid1 ========== - -The :ref:`mpl_toolkits.axes_grid1 ` toolkit is a +The :mod:`mpl_toolkits.axes_grid1` toolkit is a collection of helper classes to ease displaying multiple axes in Matplotlib. +.. image:: /_static/demo_axes_grid.png +.. toctree:: + :maxdepth: 2 -.. image:: /_static/demo_axes_grid.png + axes_grid1/index.rst .. _toolkit_axisartist: @@ -56,7 +62,16 @@ collection of helper classes to ease displaying multiple axes in Matplotlib. axisartist ========== - -The :ref:`mpl_toolkits.axisartist ` toolkit contains +The :mod:`mpl_toolkits.axisartist` toolkit contains a custom Axes class that is meant to support for curvilinear grids. +.. toctree:: + :maxdepth: 2 + + axisartist/index.rst + + +API +--- +* Axes Grid and Axis Artist API: :ref:`axes_grid-api-index` + diff --git a/doc/mpl_toolkits/mplot3d/api.rst b/doc/mpl_toolkits/mplot3d/api.rst deleted file mode 100644 index 64217a482fe2..000000000000 --- a/doc/mpl_toolkits/mplot3d/api.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _toolkit_mplot3d-api: - -*********** -mplot3d API -*********** -.. contents:: - :backlinks: none - -.. _toolkit_mplot3d-axesapi: - -:mod:`~mpl_toolkits.mplot3d.axes3d` -=================================== - -.. note:: - Significant effort went into bringing axes3d to feature-parity with - regular axes objects for version 1.1.0. However, more work remains. - Please report any functions that do not behave as expected as a bug. - In addition, help and patches would be greatly appreciated! - -.. automodule:: mpl_toolkits.mplot3d.axes3d - :members: - :undoc-members: - :show-inheritance: - - -.. _toolkit_mplot3d-axisapi: - -:mod:`~mpl_toolkits.mplot3d.axis3d` -=================================== - -.. note:: - Historically, axis3d has suffered from having hard-coded constants - controlling the look and feel of the 3D plot. This precluded user - level adjustments such as label spacing, font colors and panel colors. - For version 1.1.0, these constants have been consolidated into a single - private member dictionary, `self._axinfo`, for the axis object. This is - intended only as a stop-gap measure to allow user-level customization, - but it is not intended to be permanent. - -.. automodule:: mpl_toolkits.mplot3d.axis3d - :members: - :undoc-members: - :show-inheritance: - -.. _toolkit_mplot3d-artapi: - -:mod:`~mpl_toolkits.mplot3d.art3d` -================================== - -.. automodule:: mpl_toolkits.mplot3d.art3d - :members: - :undoc-members: - :show-inheritance: - -.. _toolkit_mplot3d-projapi: - -:mod:`~mpl_toolkits.mplot3d.proj3d` -=================================== - -.. automodule:: mpl_toolkits.mplot3d.proj3d - :members: - :undoc-members: - :show-inheritance: - diff --git a/doc/mpl_toolkits/mplot3d/index.rst b/doc/mpl_toolkits/mplot3d/index.rst index e5a7bed878be..22d2368912e9 100644 --- a/doc/mpl_toolkits/mplot3d/index.rst +++ b/doc/mpl_toolkits/mplot3d/index.rst @@ -11,6 +11,9 @@ The mplot3d toolkit adds simple 3D plotting capabilities to matplotlib by supplying an axes object that can create a 2D projection of a 3D scene. The resulting graph will have the same look and feel as regular 2D plots. +See the :ref:`mplot3d tutorial ` for +more information on how to use this toolkit. + .. image:: ../../_static/demo_mplot3d.png The interactive backends also provide the ability to rotate and zoom @@ -22,6 +25,4 @@ would use for regular 2D plots. .. toctree:: :maxdepth: 2 - tutorial.rst - api.rst faq.rst diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst index 33477ad2ce6a..25f797befdb9 100644 --- a/doc/users/prev_whats_new/whats_new_1.1.rst +++ b/doc/users/prev_whats_new/whats_new_1.1.rst @@ -137,7 +137,7 @@ as 2D plotting, Ben Root has made several improvements to the improved to bring the class towards feature-parity with regular Axes objects -* Documentation for :ref:`toolkit_mplot3d-index` was significantly expanded +* Documentation for :ref:`toolkit_mplot3d-tutorial` was significantly expanded * Axis labels and orientation improved diff --git a/lib/mpl_toolkits/axisartist/axislines.py b/lib/mpl_toolkits/axisartist/axislines.py index 5b9ff70cd1bf..4886c8574f53 100644 --- a/lib/mpl_toolkits/axisartist/axislines.py +++ b/lib/mpl_toolkits/axisartist/axislines.py @@ -76,7 +76,7 @@ class AxisArtistHelper(object): """ AxisArtistHelper should define following method with given APIs. Note that the first axes argument - will be axes attribute of the caller artist. + will be axes attribute of the caller artist.:: # LINE (spinal line?) @@ -119,7 +119,7 @@ def get_tick_iterators(self, axes): return iter_major, iter_minor - """ + """ class _Base(object): """ diff --git a/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py b/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py index 843b140aa00b..7e9de714cc83 100644 --- a/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py +++ b/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py @@ -339,8 +339,9 @@ def __init__(self, aux_trans, (inverse transform should be defined) or a tuple of two callable objects which defines the transform and its inverse. The callables need take two arguments of array of source coordinates and - should return two target coordinates: - e.g., x2, y2 = trans(x1, y1) + should return two target coordinates.:: + + e.g., x2, y2 = trans(x1, y1) """ super(GridHelperCurveLinear, self).__init__() diff --git a/lib/mpl_toolkits/mplot3d/axes3d.py b/lib/mpl_toolkits/mplot3d/axes3d.py index af627465e85d..1e2b2bdc6a02 100644 --- a/lib/mpl_toolkits/mplot3d/axes3d.py +++ b/lib/mpl_toolkits/mplot3d/axes3d.py @@ -1,10 +1,11 @@ -# axes3d.py, original mplot3d version by John Porter -# Created: 23 Sep 2005 -# Parts fixed by Reinier Heeres -# Minor additions by Ben Axelrod -# Significant updates and revisions by Ben Root - """ +axes3d.py, original mplot3d version by John Porter +Created: 23 Sep 2005 + +Parts fixed by Reinier Heeres +Minor additions by Ben Axelrod +Significant updates and revisions by Ben Root + Module containing Axes3D, an object which can plot 3D objects on a 2D matplotlib figure. """ diff --git a/tutorials/toolkits/README.txt b/tutorials/toolkits/README.txt new file mode 100644 index 000000000000..fd67eb8b8aa9 --- /dev/null +++ b/tutorials/toolkits/README.txt @@ -0,0 +1,7 @@ +.. _tutorials-toolkits: + +Toolkits +======== + +These tutorials cover toolkits designed to extend the functionality +of Matplotlib in order to accomplish specific goals. diff --git a/doc/mpl_toolkits/axes_grid1/overview.rst b/tutorials/toolkits/axes_grid.py similarity index 77% rename from doc/mpl_toolkits/axes_grid1/overview.rst rename to tutorials/toolkits/axes_grid.py index 3b0fd76c3486..d8ed396ee429 100644 --- a/doc/mpl_toolkits/axes_grid1/overview.rst +++ b/tutorials/toolkits/axes_grid.py @@ -1,25 +1,14 @@ +""" ============================== Overview of axes_grid1 toolkit ============================== -What is axes_grid1 toolkit? -=========================== - -The matplotlib axes_grid1 toolkit is a collection of helper classes, -mainly to ease displaying (multiple) images in matplotlib. - -.. contents:: - :depth: 1 - :local: +Controlling the layout of plots with the axes_grid toolkit. -.. note:: - AxesGrid toolkit has been a part of matplotlib since v - 0.99. Originally, the toolkit had a single namespace of - *axes_grid*. In more recent version, the toolkit - has divided into two separate namespace (*axes_grid1* and *axisartist*). - While *axes_grid* namespace is maintained for the backward compatibility, - use of *axes_grid1* and *axisartist* is recommended. +.. _axes_grid1_users-guide-index: +What is axes_grid1 toolkit? +=========================== *axes_grid1* is a collection of helper classes to ease displaying (multiple) images with matplotlib. In matplotlib, the axes location @@ -75,8 +64,12 @@ height. The widths (height) of the axes in the same row (column) are scaled according to their view limits (xlim or ylim). - .. plot:: mpl_toolkits/axes_grid1/examples/simple_axesgrid2.py - :include-source: + .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png + :target: ../../gallery/axes_grid1/simple_axesgrid2.html + :align: center + :scale: 50 + + Simple Axes Grid * xaxis are shared among axes in a same column. Similarly, yaxis are shared among axes in a same row. Therefore, changing axis properties @@ -171,8 +164,8 @@ Demo Axes Grid -AxesDivider ------------ +AxesDivider Class +----------------- Behind the scene, the ImageGrid class and the RGBAxes class utilize the AxesDivider class, whose role is to calculate the location of the axes @@ -183,8 +176,8 @@ which can be useful. It takes a existing axes instance and create a divider for it. :: - ax = subplot(1,1,1) - divider = make_axes_locatable(ax) + ax = subplot(1,1,1) + divider = make_axes_locatable(ax) @@ -411,14 +404,104 @@ Simple Rgb +AxesDivider +=========== + +The axes_divider module provide helper classes to adjust the axes +positions of set of images in the drawing time. + +* :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a classes of + units that the size of each axes will be determined. For example, + you can specify a fixed size + +* :class:`~mpl_toolkits.axes_grid1.axes_size.Divider` this is the class + that is used calculates the axes position. It divides the given + rectangular area into several areas. You initialize the divider by + setting the horizontal and vertical list of sizes that the division + will be based on. You then use the new_locator method, whose return + value is a callable object that can be used to set the axes_locator + of the axes. + + +You first initialize the divider by specifying its grids, i.e., +horizontal and vertical. +for example,:: + rect = [0.2, 0.2, 0.6, 0.6] + horiz=[h0, h1, h2, h3] + vert=[v0, v1, v2] + divider = Divider(fig, rect, horiz, vert) +where, rect is a bounds of the box that will be divided and h0,..h3, +v0,..v2 need to be an instance of classes in the +:mod:`~mpl_toolkits.axes_grid1.axes_size`. They have *get_size* method +that returns a tuple of two floats. The first float is the relative +size, and the second float is the absolute size. Consider a following +grid. ++-----+-----+-----+-----+ +| v0 | | | | ++-----+-----+-----+-----+ +| v1 | | | | ++-----+-----+-----+-----+ +|h0,v2| h1 | h2 | h3 | ++-----+-----+-----+-----+ +* v0 => 0, 2 +* v1 => 2, 0 +* v2 => 3, 0 +The height of the bottom row is always 2 (axes_divider internally +assumes that the unit is inch). The first and the second rows with +height ratio of 2:3. For example, if the total height of the grid 6, +then the first and second row will each occupy 2/(2+3) and 3/(2+3) of +(6-1) inches. The widths of columns (horiz) will be similarly +determined. When aspect ratio is set, the total height (or width) will +be adjusted accordingly. +The :mod:`mpl_toolkits.axes_grid1.axes_size` contains several classes +that can be used to set the horizontal and vertical configurations. For +example, for the vertical configuration above will be:: + from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled + vert = [Fixed(2), Scaled(2), Scaled(3)] + +After you set up the divider object, then you create a locator +instance which will be given to the axes.:: + + locator = divider.new_locator(nx=0, ny=1) + ax.set_axes_locator(locator) + +The return value of the new_locator method is a instance of the +AxesLocator class. It is a callable object that returns the +location and size of the cell at the first column and the second row. +You may create a locator that spans over multiple cells.:: + + locator = divider.new_locator(nx=0, nx=2, ny=1) + +The above locator, when called, will return the position and size of +the cells spanning the first and second column and the first row. You +may consider it as [0:2, 1]. + +See the example, + +.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider2_001.png + :target: ../../gallery/axes_grid1/simple_axes_divider2.html + :align: center + :scale: 50 + + Simple Axes Divider2 + +You can adjust the size of the each axes according to their x or y +data limits (AxesX and AxesY), similar to the axes aspect parameter. + +.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png + :target: ../../gallery/axes_grid1/simple_axes_divider3.html + :align: center + :scale: 50 + Simple Axes Divider3 +""" diff --git a/doc/mpl_toolkits/axisartist/users/axisartist.rst b/tutorials/toolkits/axisartist.py similarity index 72% rename from doc/mpl_toolkits/axisartist/users/axisartist.rst rename to tutorials/toolkits/axisartist.py index 958656a3177e..b1a476bfcefc 100644 --- a/doc/mpl_toolkits/axisartist/users/axisartist.rst +++ b/tutorials/toolkits/axisartist.py @@ -1,6 +1,153 @@ -.. _axisartist-manual: +""" +============================== +Overview of axisartist toolkit +============================== + +The axisartist toolkit tutorial. + +.. warning:: + *axisartist* uses a custom Axes class + (derived from the mpl's original Axes class). + As a side effect, some commands (mostly tick-related) do not work. + +The *axisartist* contains custom Axes class that is meant to support for +curvilinear grids (e.g., the world coordinate system in astronomy). +Unlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis +to draw ticks, ticklines and etc., Axes in axisartist uses special +artist (AxisArtist) which can handle tick, ticklines and etc. for +curved coordinate systems. + +.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png + :target: ../../gallery/axisartist/demo_floating_axis.html + :align: center + :scale: 50 + + Demo Floating Axis + +Since it uses special artists, some mpl commands that work on +Axes.xaxis and Axes.yaxis may not work. + +.. _axisartist_users-guide-index: + +axisartist +========== + +*axisartist* module provides a custom (and very experimental) Axes +class, where each axis (left, right, top and bottom) have a separate +associated artist which is responsible to draw axis-line, ticks, +ticklabels, label. Also, you can create your own axis, which can pass +through a fixed position in the axes coordinate, or a fixed position +in the data coordinate (i.e., the axis floats around when viewlimit +changes). + +The axes class, by default, has its xaxis and yaxis invisible, and +has 4 additional artists which are responsible for drawing the 4 axis sides in +"left","right","bottom" and "top". They are accessed as +ax.axis["left"], ax.axis["right"], and so on, i.e., ax.axis is a +dictionary that contains artists (note that ax.axis is still a +callable methods and it behaves as an original Axes.axis method in +mpl). + +To create an axes, :: + + import mpl_toolkits.axisartist as AA + fig = plt.figure(1) + ax = AA.Axes(fig, [0.1, 0.1, 0.8, 0.8]) + fig.add_axes(ax) + +or to create a subplot :: + + ax = AA.Subplot(fig, 111) + fig.add_subplot(ax) + +For example, you can hide the right, and top axis by :: + + ax.axis["right"].set_visible(False) + ax.axis["top"].set_visible(False) + + +.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axisline3_001.png + :target: ../../gallery/userdemo/simple_axisline3.html + :align: center + :scale: 50 + + Simple Axisline3 + + +It is also possible to add an extra axis. For example, you may have an +horizontal axis at y=0 (in data coordinate). :: + + ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0) + +.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axisartist1_001.png + :target: ../../gallery/userdemo/simple_axisartist1.html + :align: center + :scale: 50 + + Simple Axisartist1 + + +Or a fixed axis with some offset :: + + # make new (right-side) yaxis, but wth some offset + ax.axis["right2"] = ax.new_fixed_axis(loc="right", + offset=(20, 0)) + + + +axisartist with ParasiteAxes +---------------------------- + +Most commands in the axes_grid1 toolkit can take a axes_class keyword +argument, and the commands creates an axes of the given class. For example, +to create a host subplot with axisartist.Axes, :: + + import mpl_toolkits.axisartist as AA + from mpl_toolkits.axes_grid1 import host_subplot + + host = host_subplot(111, axes_class=AA.Axes) + + +Here is an example that uses parasiteAxes. + + +.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png + :target: ../../gallery/axisartist/demo_parasite_axes2.html + :align: center + :scale: 50 + + Demo Parasite Axes2 + + + +Curvilinear Grid +---------------- + +The motivation behind the AxisArtist module is to support curvilinear grid +and ticks. + +.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png + :target: ../../gallery/axisartist/demo_curvelinear_grid.html + :align: center + :scale: 50 + + Demo Curvelinear Grid + + +Floating Axes +------------- + +This also support a Floating Axes whose outer axis are defined as +floating axis. + +.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png + :target: ../../gallery/axisartist/demo_floating_axes.html + :align: center + :scale: 50 + + Demo Floating Axes + -==================== axisartist namespace ==================== @@ -29,8 +176,8 @@ * a curvilinear grid. * a floating axis -.. figure:: ../../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png - :target: ../../../gallery/axisartist/demo_floating_axis.html +.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png + :target: ../../gallery/axisartist/demo_floating_axis.html :align: center :scale: 50 @@ -98,7 +245,7 @@ Default AxisArtists -------------------- +=================== By default, following for axis artists are defined.:: @@ -200,8 +347,8 @@ ax1.axis["left"].major_ticklabels.set_axis_direction("top") ax1.axis["right"].label.set_axis_direction("left") -.. figure:: ../../../gallery/userdemo/images/sphx_glr_simple_axis_direction01_001.png - :target: ../../../gallery/userdemo/simple_axis_direction01.html +.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axis_direction01_001.png + :target: ../../gallery/userdemo/simple_axis_direction01.html :align: center :scale: 50 @@ -216,8 +363,8 @@ of the axis line with increasing coordinate. For example, the reference direction of the left x-axis is from bottom to top. - .. figure:: ../../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step01_001.png - :target: ../../../gallery/userdemo/axis_direction_demo_step01.html + .. figure:: ../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step01_001.png + :target: ../../gallery/userdemo/axis_direction_demo_step01.html :align: center :scale: 50 @@ -229,8 +376,8 @@ 2. *ticklabel_direction* is either the right-hand side (+) of the reference direction or the left-hand side (-). - .. figure:: ../../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step02_001.png - :target: ../../../gallery/userdemo/axis_direction_demo_step02.html + .. figure:: ../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step02_001.png + :target: ../../gallery/userdemo/axis_direction_demo_step02.html :align: center :scale: 50 @@ -238,8 +385,8 @@ 3. same for the *label_direction* - .. figure:: ../../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step03_001.png - :target: ../../../gallery/userdemo/axis_direction_demo_step03.html + .. figure:: ../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step03_001.png + :target: ../../gallery/userdemo/axis_direction_demo_step03.html :align: center :scale: 50 @@ -251,8 +398,8 @@ to the *ticklabel_direction* or *label_direction*, respectively. The rotation of ticklabels and label is anchored. - .. figure:: ../../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step04_001.png - :target: ../../../gallery/userdemo/axis_direction_demo_step04.html + .. figure:: ../../gallery/userdemo/images/sphx_glr_axis_direction_demo_step04_001.png + :target: ../../gallery/userdemo/axis_direction_demo_step04.html :align: center :scale: 50 @@ -281,8 +428,8 @@ etc, for settings suitable for "top" axis. The concept of axis direction can be more clear with curved axis. -.. figure:: ../../../gallery/userdemo/images/sphx_glr_demo_axis_direction_001.png - :target: ../../../gallery/userdemo/demo_axis_direction.html +.. figure:: ../../gallery/userdemo/images/sphx_glr_demo_axis_direction_001.png + :target: ../../gallery/userdemo/demo_axis_direction.html :align: center :scale: 50 @@ -316,8 +463,8 @@ ax.axis[:].major_ticks.set_tick_out(True) -.. figure:: ../../../gallery/userdemo/images/sphx_glr_simple_axis_direction03_001.png - :target: ../../../gallery/userdemo/simple_axis_direction03.html +.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axis_direction03_001.png + :target: ../../gallery/userdemo/simple_axis_direction03.html :align: center :scale: 50 @@ -350,8 +497,8 @@ Alignment of TickLabels are treated specially. See below -.. figure:: ../../../gallery/userdemo/images/sphx_glr_demo_ticklabel_alignment_001.png - :target: ../../../gallery/userdemo/demo_ticklabel_alignment.html +.. figure:: ../../gallery/userdemo/images/sphx_glr_demo_ticklabel_alignment_001.png + :target: ../../gallery/userdemo/demo_ticklabel_alignment.html :align: center :scale: 50 @@ -369,8 +516,8 @@ ax.axis["left"].label.set_pad(10) -.. figure:: ../../../gallery/userdemo/images/sphx_glr_simple_axis_pad_001.png - :target: ../../../gallery/userdemo/simple_axis_pad.html +.. figure:: ../../gallery/userdemo/images/sphx_glr_simple_axis_pad_001.png + :target: ../../gallery/userdemo/simple_axis_pad.html :align: center :scale: 50 @@ -468,8 +615,8 @@ def inv_tr(x,y): ax1.parasites.append(ax2) -.. figure:: ../../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png - :target: ../../../gallery/axisartist/demo_curvelinear_grid.html +.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png + :target: ../../gallery/axisartist/demo_curvelinear_grid.html :align: center :scale: 50 @@ -510,10 +657,4 @@ def inv_tr(x,y): * The location of axislabel of FloatingAxis needs to be optionally given as a coordinate value. ex, a floating axis of x=0 with label at y=1 - - - - - - - +""" diff --git a/doc/mpl_toolkits/mplot3d/tutorial.rst b/tutorials/toolkits/mplot3d.py similarity index 95% rename from doc/mpl_toolkits/mplot3d/tutorial.rst rename to tutorials/toolkits/mplot3d.py index f3ce4baa02fb..826fe1ed354b 100644 --- a/doc/mpl_toolkits/mplot3d/tutorial.rst +++ b/tutorials/toolkits/mplot3d.py @@ -1,16 +1,19 @@ -.. _toolkit_mplot3d-tutorial: +""" +=================== +The mplot3d Toolkit +=================== + +Generating 3D plots the mplot3d toolkit. + .. currentmodule:: mpl_toolkits.mplot3d -**************** -mplot3d tutorial -**************** .. contents:: :backlinks: none -.. _mplot3d_getting_started: +.. _toolkit_mplot3d-tutorial: Getting started -=============== +--------------- An Axes3D object is created just like any other axes using the projection='3d' keyword. Create a new :class:`matplotlib.figure.Figure` and @@ -30,6 +33,9 @@ ``ax = fig.add_subplot(111, projection='3d')`` to ``ax = Axes3D(fig)``. +See the :ref:`toolkit_mplot3d-faq` for more information about the mplot3d +toolkit. + .. _plot3d: Line plots @@ -219,23 +225,4 @@ Subplot3d Mixed Subplots - - - - - - - - - - - - - - - - - - - - +""" From b7d733ebb2bfe6264e2f3a4bbe4098f540a2795c Mon Sep 17 00:00:00 2001 From: Christopher Holdgraf Date: Tue, 9 May 2017 09:53:13 -0700 Subject: [PATCH 2/5] addressing comments --- doc/api/toolkits/axes_grid.rst | 8 +++++++- doc/api/toolkits/mplot3d.rst | 20 +++++++++---------- .../axisartist/grid_helper_curvelinear.py | 4 ++-- tutorials/toolkits/mplot3d.py | 10 +++++----- 4 files changed, 23 insertions(+), 19 deletions(-) diff --git a/doc/api/toolkits/axes_grid.rst b/doc/api/toolkits/axes_grid.rst index e70d57de3a60..8f530f9bf3f4 100644 --- a/doc/api/toolkits/axes_grid.rst +++ b/doc/api/toolkits/axes_grid.rst @@ -11,11 +11,17 @@ The Matplotlib axes_grid Toolkit API Axes Grid --------- +.. note:: + + There is an older version of the AxesGrid toolkit, simply called ``axes_grid`` instead of + ``axes_grid1``. the toolkit had a single namespace of axes_grid. This toolkit was broken + into the two modules below. For the documentation on the original ``axes_grid`` + module, see the `previous version of the docs + `_. .. autosummary:: :toctree: ../_as_gen :template: automodule.rst - axes_grid axes_grid1 axisartist diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst index a0355207cb66..0460bb780d0a 100644 --- a/doc/api/toolkits/mplot3d.rst +++ b/doc/api/toolkits/mplot3d.rst @@ -24,12 +24,7 @@ mplot3d API :toctree: ../_as_gen :template: autosummary.rst - axes3d.Axes axes3d.Axes3D - axes3d.Bbox - axes3d.LightSource - axes3d.Normalize - axes3d.Triangulation .. _toolkit_mplot3d-axisapi: @@ -51,12 +46,6 @@ mplot3d API :template: autosummary.rst axis3d.Axis - axis3d.XAxis - axis3d.YAxis - axis3d.ZAxis - axis3d.get_flip_min_max - axis3d.move_from_center - axis3d.tick_update_position .. _toolkit_mplot3d-artapi: @@ -76,6 +65,15 @@ mplot3d API art3d.PathPatch3D art3d.Poly3DCollection art3d.Text3D + + +Art3D Utility Functions +======================= + +.. autosummary:: + :toctree: ../_as_gen + :template: autosummary.rst + art3d.get_colors art3d.get_dir_vector art3d.get_patch_verts diff --git a/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py b/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py index 7e9de714cc83..25b623c2a773 100644 --- a/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py +++ b/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py @@ -339,9 +339,9 @@ def __init__(self, aux_trans, (inverse transform should be defined) or a tuple of two callable objects which defines the transform and its inverse. The callables need take two arguments of array of source coordinates and - should return two target coordinates.:: + should return two target coordinates. - e.g., x2, y2 = trans(x1, y1) + e.g., ``x2, y2 = trans(x1, y1)`` """ super(GridHelperCurveLinear, self).__init__() diff --git a/tutorials/toolkits/mplot3d.py b/tutorials/toolkits/mplot3d.py index 826fe1ed354b..212481ee9fe0 100644 --- a/tutorials/toolkits/mplot3d.py +++ b/tutorials/toolkits/mplot3d.py @@ -3,7 +3,7 @@ The mplot3d Toolkit =================== -Generating 3D plots the mplot3d toolkit. +Generating 3D plots using the mplot3d toolkit. .. currentmodule:: mpl_toolkits.mplot3d @@ -19,10 +19,10 @@ Create a new :class:`matplotlib.figure.Figure` and add a new axes to it of type :class:`~mpl_toolkits.mplot3d.Axes3D`:: - import matplotlib.pyplot as plt - from mpl_toolkits.mplot3d import Axes3D - fig = plt.figure() - ax = fig.add_subplot(111, projection='3d') + import matplotlib.pyplot as plt + from mpl_toolkits.mplot3d import Axes3D + fig = plt.figure() + ax = fig.add_subplot(111, projection='3d') .. versionadded:: 1.0.0 This approach is the preferred method of creating a 3D axes. From 2b00840a4eef1b6a02aa01a0bb99b129f6d2d302 Mon Sep 17 00:00:00 2001 From: Christopher Holdgraf Date: Tue, 16 May 2017 09:35:41 -0700 Subject: [PATCH 3/5] addressing comments --- doc/api/toolkits/axes_grid.rst | 9 ++-- doc/api/toolkits/mplot3d.rst | 14 +++---- doc/mpl_toolkits/axisartist/index.rst | 10 ++--- doc/mpl_toolkits/index.rst | 8 ++-- lib/mpl_toolkits/axisartist/axislines.py | 9 ++-- tutorials/toolkits/axes_grid.py | 53 ++++++++++++------------ tutorials/toolkits/axisartist.py | 38 ++++++++--------- 7 files changed, 71 insertions(+), 70 deletions(-) diff --git a/doc/api/toolkits/axes_grid.rst b/doc/api/toolkits/axes_grid.rst index 8f530f9bf3f4..0d9f4b32ffdf 100644 --- a/doc/api/toolkits/axes_grid.rst +++ b/doc/api/toolkits/axes_grid.rst @@ -13,10 +13,11 @@ Axes Grid --------- .. note:: - There is an older version of the AxesGrid toolkit, simply called ``axes_grid`` instead of - ``axes_grid1``. the toolkit had a single namespace of axes_grid. This toolkit was broken - into the two modules below. For the documentation on the original ``axes_grid`` - module, see the `previous version of the docs + There is an older version of the AxesGrid toolkit, ``axes_grid`` (instead of + ``axes_grid1``). The old version had a single namespace for all axes_grid + objects, and in the new version this toolkit was broken + into the two modules below. For the documentation on ``axes_grid``, + see the `previous version of the docs `_. .. autosummary:: diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst index 0460bb780d0a..99283977504a 100644 --- a/doc/api/toolkits/mplot3d.rst +++ b/doc/api/toolkits/mplot3d.rst @@ -33,13 +33,13 @@ mplot3d API =================================== .. note:: - Historically, axis3d has suffered from having hard-coded constants - controlling the look and feel of the 3D plot. This precluded user - level adjustments such as label spacing, font colors and panel colors. - For version 1.1.0, these constants have been consolidated into a single - private member dictionary, `self._axinfo`, for the axis object. This is - intended only as a stop-gap measure to allow user-level customization, - but it is not intended to be permanent. + See :attr:`mpl_toolkits.mplot3d.axis3d._axinfo` for a dictionary containing + constants that may be modified for controlling the look and feel + of mplot3d axes (e.g., label spacing, font colors and panel colors). + Historically, axis3d has suffered from having hard-coded constants + that precluded user adjustments, and this dictionary was implemented + in version 1.1 as a stop-gap measure. + .. autosummary:: :toctree: ../_as_gen diff --git a/doc/mpl_toolkits/axisartist/index.rst b/doc/mpl_toolkits/axisartist/index.rst index 4bb80df51fee..2a46936f1381 100644 --- a/doc/mpl_toolkits/axisartist/index.rst +++ b/doc/mpl_toolkits/axisartist/index.rst @@ -3,11 +3,11 @@ Matplotlib axisartist Toolkit ============================= -The *axisartist* namespace includes a derived Axes implementation. The -biggest difference is that the artists responsible to draw axis line, -ticks, ticklabel and axis labels are separated out from the mpl's Axis -class, which are much more than artists in the original mpl. This -change was strongly motivated to support curvilinear grid. +The *axisartist* namespace includes a derived Axes implementation ( +:class:`mpl_toolkits.axisartist.Axes`). The +biggest difference is that the artists that are responsible for drawing +axis lines, ticks, ticklabels, and axis labels are separated out from the +mpl's Axis class. This change was strongly motivated to support curvilinear grid. You can find a tutorial describing usage of axisartist at :ref:`axisartist_users-guide-index`. diff --git a/doc/mpl_toolkits/index.rst b/doc/mpl_toolkits/index.rst index ba9f3337627d..285f9d49295a 100644 --- a/doc/mpl_toolkits/index.rst +++ b/doc/mpl_toolkits/index.rst @@ -18,8 +18,8 @@ mplot3d ======= :mod:`mpl_toolkits.mplot3d` provides some basic 3D -plotting (scatter, surf, line, mesh) tools. Not the fastest or feature -complete 3D library out there, but ships with Matplotlib and thus may be a +plotting (scatter, surf, line, mesh) tools. Not the fastest or most feature +complete 3D library out there, but it ships with Matplotlib and thus may be a lighter weight solution for some use cases. Check out the :ref:`mplot3d tutorial ` for more information. @@ -47,7 +47,7 @@ axes_grid1 ========== The :mod:`mpl_toolkits.axes_grid1` toolkit is a -collection of helper classes to ease displaying multiple axes in Matplotlib. +collection of helper classes for displaying multiple axes in Matplotlib. .. image:: /_static/demo_axes_grid.png @@ -63,7 +63,7 @@ axisartist ========== The :mod:`mpl_toolkits.axisartist` toolkit contains -a custom Axes class that is meant to support for curvilinear grids. +a custom Axes class that is meant to support curvilinear grids. .. toctree:: :maxdepth: 2 diff --git a/lib/mpl_toolkits/axisartist/axislines.py b/lib/mpl_toolkits/axisartist/axislines.py index 4886c8574f53..ca735b94bdf2 100644 --- a/lib/mpl_toolkits/axisartist/axislines.py +++ b/lib/mpl_toolkits/axisartist/axislines.py @@ -1,10 +1,9 @@ """ Axislines includes modified implementation of the Axes class. The -biggest difference is that the artists responsible to draw axis line, -ticks, ticklabel and axis labels are separated out from the mpl's Axis -class, which are much more than artists in the original -mpl. Originally, this change was motivated to support curvilinear -grid. Here are a few reasons that I came up with new axes class. +biggest difference is that the artists responsible for drawing the axis spine, +ticks, ticklabels and axis labels are separated out from mpl's Axis +class. Originally, this change was motivated to support curvilinear +grid. Here are a few reasons that I came up with a new axes class: * "top" and "bottom" x-axis (or "left" and "right" y-axis) can have diff --git a/tutorials/toolkits/axes_grid.py b/tutorials/toolkits/axes_grid.py index d8ed396ee429..0b76b9c4fa3b 100644 --- a/tutorials/toolkits/axes_grid.py +++ b/tutorials/toolkits/axes_grid.py @@ -14,7 +14,7 @@ (multiple) images with matplotlib. In matplotlib, the axes location (and size) is specified in the normalized figure coordinates, which may not be ideal for displaying images that needs to have a given -aspect ratio. For example, it helps you to have a colorbar whose +aspect ratio. For example, it helps if you have a colorbar whose height always matches that of the image. `ImageGrid`_, `RGB Axes`_ and `AxesDivider`_ are helper classes that deals with adjusting the location of (multiple) Axes. They provides a framework to adjust the @@ -276,7 +276,7 @@ Example 2. twin ~~~~~~~~~~~~~~~ -*twin* without a transform argument treat the parasite axes to have a +*twin* without a transform argument assumes that the parasite axes has the same data transform as the host. This can be useful when you want the top(or right)-axis to have different tick-locations, tick-labels, or tick-formatter for bottom(or left)-axis. :: @@ -407,23 +407,24 @@ AxesDivider =========== -The axes_divider module provide helper classes to adjust the axes -positions of set of images in the drawing time. +The axes_divider module provides helper classes to adjust the axes +positions of a set of images at drawing time. -* :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a classes of - units that the size of each axes will be determined. For example, - you can specify a fixed size +* :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a class of + units that are used to determine the size of each axes. For example, + you can specify a fixed size. -* :class:`~mpl_toolkits.axes_grid1.axes_size.Divider` this is the class - that is used calculates the axes position. It divides the given - rectangular area into several areas. You initialize the divider by - setting the horizontal and vertical list of sizes that the division - will be based on. You then use the new_locator method, whose return - value is a callable object that can be used to set the axes_locator - of the axes. +* :class:`~mpl_toolkits.axes_grid1.axes_size.Divider` is the class + that calculates the axes position. It divides the given + rectangular area into several areas. The divider is initialized by + setting the lists of horizontal and vertical sizes on which the division + will be based. Then use + :meth:`~mpl_toolkits.axes_grid1.axes_size.Divider.new_locator`, + which returns a callable object that can be used to set the + axes_locator of the axes. -You first initialize the divider by specifying its grids, i.e., +First, initialize the divider by specifying its grids, i.e., horizontal and vertical. for example,:: @@ -454,28 +455,28 @@ * v2 => 3, 0 The height of the bottom row is always 2 (axes_divider internally -assumes that the unit is inch). The first and the second rows with -height ratio of 2:3. For example, if the total height of the grid 6, +assumes that the unit is inches). The first and the second rows have a +height ratio of 2:3. For example, if the total height of the grid is 6, then the first and second row will each occupy 2/(2+3) and 3/(2+3) of -(6-1) inches. The widths of columns (horiz) will be similarly -determined. When aspect ratio is set, the total height (or width) will +(6-1) inches. The widths of the horizontal columns will be similarly +determined. When the aspect ratio is set, the total height (or width) will be adjusted accordingly. The :mod:`mpl_toolkits.axes_grid1.axes_size` contains several classes that can be used to set the horizontal and vertical configurations. For -example, for the vertical configuration above will be:: +example, for vertical configuration one could use:: from mpl_toolkits.axes_grid1.axes_size import Fixed, Scaled vert = [Fixed(2), Scaled(2), Scaled(3)] After you set up the divider object, then you create a locator -instance which will be given to the axes.:: +instance that will be given to the axes object.:: locator = divider.new_locator(nx=0, ny=1) ax.set_axes_locator(locator) -The return value of the new_locator method is a instance of the +The return value of the new_locator method is an instance of the AxesLocator class. It is a callable object that returns the location and size of the cell at the first column and the second row. You may create a locator that spans over multiple cells.:: @@ -483,8 +484,8 @@ locator = divider.new_locator(nx=0, nx=2, ny=1) The above locator, when called, will return the position and size of -the cells spanning the first and second column and the first row. You -may consider it as [0:2, 1]. +the cells spanning the first and second column and the first row. In +this example, it will return [0:2, 1]. See the example, @@ -495,8 +496,8 @@ Simple Axes Divider2 -You can adjust the size of the each axes according to their x or y -data limits (AxesX and AxesY), similar to the axes aspect parameter. +You can adjust the size of each axes according to its x or y +data limits (AxesX and AxesY). .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png :target: ../../gallery/axes_grid1/simple_axes_divider3.html diff --git a/tutorials/toolkits/axisartist.py b/tutorials/toolkits/axisartist.py index b1a476bfcefc..38866978179f 100644 --- a/tutorials/toolkits/axisartist.py +++ b/tutorials/toolkits/axisartist.py @@ -10,11 +10,11 @@ (derived from the mpl's original Axes class). As a side effect, some commands (mostly tick-related) do not work. -The *axisartist* contains custom Axes class that is meant to support for +The *axisartist* contains a custom Axes class that is meant to support curvilinear grids (e.g., the world coordinate system in astronomy). Unlike mpl's original Axes class which uses Axes.xaxis and Axes.yaxis -to draw ticks, ticklines and etc., Axes in axisartist uses special -artist (AxisArtist) which can handle tick, ticklines and etc. for +to draw ticks, ticklines, etc., axisartist uses a special +artist (AxisArtist) that can handle ticks, ticklines, etc. for curved coordinate systems. .. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png @@ -24,7 +24,7 @@ Demo Floating Axis -Since it uses special artists, some mpl commands that work on +Since it uses special artists, some Matplotlib commands that work on Axes.xaxis and Axes.yaxis may not work. .. _axisartist_users-guide-index: @@ -32,21 +32,21 @@ axisartist ========== -*axisartist* module provides a custom (and very experimental) Axes -class, where each axis (left, right, top and bottom) have a separate -associated artist which is responsible to draw axis-line, ticks, -ticklabels, label. Also, you can create your own axis, which can pass +The *axisartist* module provides a custom (and very experimental) Axes +class, where each axis (left, right, top, and bottom) have a separate +associated artist which is responsible for drawing the axis-line, ticks, +ticklabels, and labels. You can also create your own axis, which can pass through a fixed position in the axes coordinate, or a fixed position in the data coordinate (i.e., the axis floats around when viewlimit changes). The axes class, by default, has its xaxis and yaxis invisible, and -has 4 additional artists which are responsible for drawing the 4 axis sides in -"left","right","bottom" and "top". They are accessed as +has 4 additional artists which are responsible for drawing the 4 axis spines in +"left", "right", "bottom", and "top". They are accessed as ax.axis["left"], ax.axis["right"], and so on, i.e., ax.axis is a dictionary that contains artists (note that ax.axis is still a -callable methods and it behaves as an original Axes.axis method in -mpl). +callable method and it behaves as an original Axes.axis method in +Matplotlib). To create an axes, :: @@ -60,7 +60,7 @@ ax = AA.Subplot(fig, 111) fig.add_subplot(ax) -For example, you can hide the right, and top axis by :: +For example, you can hide the right and top spines using:: ax.axis["right"].set_visible(False) ax.axis["top"].set_visible(False) @@ -74,7 +74,7 @@ Simple Axisline3 -It is also possible to add an extra axis. For example, you may have an +It is also possible to add a horizontal axis. For example, you may have an horizontal axis at y=0 (in data coordinate). :: ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0) @@ -98,8 +98,8 @@ axisartist with ParasiteAxes ---------------------------- -Most commands in the axes_grid1 toolkit can take a axes_class keyword -argument, and the commands creates an axes of the given class. For example, +Most commands in the axes_grid1 toolkit can take an axes_class keyword +argument, and the commands create an axes of the given class. For example, to create a host subplot with axisartist.Axes, :: import mpl_toolkits.axisartist as AA @@ -108,7 +108,7 @@ host = host_subplot(111, axes_class=AA.Axes) -Here is an example that uses parasiteAxes. +Here is an example that uses parasiteAxes. .. figure:: ../../gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png @@ -123,7 +123,7 @@ Curvilinear Grid ---------------- -The motivation behind the AxisArtist module is to support curvilinear grid +The motivation behind the AxisArtist module is to support a curvilinear grid and ticks. .. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png @@ -137,7 +137,7 @@ Floating Axes ------------- -This also support a Floating Axes whose outer axis are defined as +AxisArtist also supports a Floating Axes whose outer axes are defined as floating axis. .. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png From c4e2611afe1da2d3d36c5ae91d330b455f63e1ea Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Tue, 16 May 2017 10:20:10 -0700 Subject: [PATCH 4/5] updating CSS for links --- doc/_static/mpl.css | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 1c75454512bf..9f0c847dccef 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -19,10 +19,18 @@ body { } a { - color: #CA7900 !important; + color: #CA7900; text-decoration: none; } +div.highlight-python a { + color: #CA7900; +} + +div.highlight-python a:hover { + color: #2491CF; +} + strong { font-weight: strong; } From 642fc494ba5ecddda01aab6dd205e7754dcb5f34 Mon Sep 17 00:00:00 2001 From: Christopher Holdgraf Date: Thu, 18 May 2017 09:39:48 -0700 Subject: [PATCH 5/5] final touches --- doc/api/toolkits/axes_grid.rst | 2 +- doc/api/toolkits/mplot3d.rst | 6 +++--- tutorials/toolkits/axes_grid.py | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/api/toolkits/axes_grid.rst b/doc/api/toolkits/axes_grid.rst index 0d9f4b32ffdf..ed8692fcc016 100644 --- a/doc/api/toolkits/axes_grid.rst +++ b/doc/api/toolkits/axes_grid.rst @@ -18,7 +18,7 @@ Axes Grid objects, and in the new version this toolkit was broken into the two modules below. For the documentation on ``axes_grid``, see the `previous version of the docs - `_. + `_. .. autosummary:: :toctree: ../_as_gen diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst index 99283977504a..f66b833ac51b 100644 --- a/doc/api/toolkits/mplot3d.rst +++ b/doc/api/toolkits/mplot3d.rst @@ -36,9 +36,9 @@ mplot3d API See :attr:`mpl_toolkits.mplot3d.axis3d._axinfo` for a dictionary containing constants that may be modified for controlling the look and feel of mplot3d axes (e.g., label spacing, font colors and panel colors). - Historically, axis3d has suffered from having hard-coded constants - that precluded user adjustments, and this dictionary was implemented - in version 1.1 as a stop-gap measure. + Historically, axis3d has suffered from having hard-coded constants + that precluded user adjustments, and this dictionary was implemented + in version 1.1 as a stop-gap measure. .. autosummary:: diff --git a/tutorials/toolkits/axes_grid.py b/tutorials/toolkits/axes_grid.py index 0b76b9c4fa3b..a1af2c0cbc11 100644 --- a/tutorials/toolkits/axes_grid.py +++ b/tutorials/toolkits/axes_grid.py @@ -245,7 +245,7 @@ The ParasiteAxes is an axes whose location is identical to its host axes. The location is adjusted in the drawing time, thus it works even -if the host change its location (e.g., images). +if the host change its location (e.g., images). In most cases, you first create a host axes, which provides a few method that can be used to create parasite axes. They are *twinx*, @@ -276,7 +276,7 @@ Example 2. twin ~~~~~~~~~~~~~~~ -*twin* without a transform argument assumes that the parasite axes has the +*twin* without a transform argument assumes that the parasite axes has the same data transform as the host. This can be useful when you want the top(or right)-axis to have different tick-locations, tick-labels, or tick-formatter for bottom(or left)-axis. ::