Merge pull request matplotlib#8573 from choldgraf/sg_mpl_toolkit

SG for toolkits

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;
 }

doc/_templates/automodule.rst

@@ -5,24 +5,22 @@
    :no-members:
    :no-inherited-members:
 
-{% block functions %}
-{% if functions %}
+{% block classes %}
+{% if classes %}
 
 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 %}

doc/api/index.rst

@@ -66,3 +66,13 @@
    :template: autofunctions.rst
 
    pyplot
+
+
+Toolkits
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   toolkits/axes_grid.rst
+   toolkits/mplot3d.rst

doc/api/toolkits/axes_grid.rst

@@ -0,0 +1,28 @@
+.. _axes_grid-api-index:
+
+####################################
+The Matplotlib axes_grid Toolkit API
+####################################
+
+:Release: |version|
+:Date: |today|
+
+.. currentmodule:: mpl_toolkits
+
+Axes Grid
+---------
+.. note::
+
+   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 
+   <https://matplotlib.org/2.0.1/mpl_toolkits/axes_grid/index.html#toolkit-axesgrid-index>`_.
+
+.. autosummary::
+   :toctree: ../_as_gen
+   :template: automodule.rst
+
+   axes_grid1
+   axisartist

doc/api/toolkits/mplot3d.rst

@@ -0,0 +1,124 @@
+.. _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.Axes3D
+
+
+.. _toolkit_mplot3d-axisapi:
+
+:mod:`~mpl_toolkits.mplot3d.axis3d`
+===================================
+
+.. note::
+   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
+   :template: autosummary.rst
+
+   axis3d.Axis
+
+
+.. _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 Utility Functions
+=======================
+
+.. autosummary::
+   :toctree: ../_as_gen
+   :template: autosummary.rst
+
+   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

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/"

doc/make.py

@@ -162,12 +162,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):
@@ -203,40 +199,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='*')