Update API changes page

dstansby · tacaswell · commit 21f214a8c667 · 2019-04-14T15:51:02.000-04:00
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -3,20 +3,18 @@
 API Changes
 ===========
 
-A log of changes to the most recent version of Matplotlib that affect the
-outward-facing API. If updating Matplotlib breaks your scripts, this list may
-help you figure out what caused the breakage and how to fix it by updating
-your code. For API changes in older versions see :doc:`api_changes_old`.
+If updating Matplotlib breaks your scripts, this list may help you figure out
+what caused the breakage and how to fix it by updating your code.
 
-For new features that were added to Matplotlib, see :ref:`whats-new`.
-
-This pages lists API changes for the most recent version of Matplotlib.
+For API changes in older versions see
 
 .. toctree::
    :maxdepth: 1
 
    api_changes_old
 
+Changes for the latest version are listed below. For new features that were
+added to Matplotlib, see :ref:`whats-new`.
 
 .. note::
 
@@ -25,14 +23,17 @@ This pages lists API changes for the most recent version of Matplotlib.
 
    When a release is made
 
-    - The full text list below should be moved into its own file in
-      'prev_api_changes'
-    - All the files in 'next_api_changes' should be moved to the bottom of this page
-    - This note, and the toctree below should be commented out
+    - All the files in 'next_api_changes/' should be moved to a single file in
+      'prev_api_changes/'.
+    - The include directive below should be changed to point to the new file
+      created in the previous step.
+    - This note, and the toctree below should be commented out.
 
 
 .. toctree::
    :glob:
    :maxdepth: 1
 
    next_api_changes/*
+
+.. include:: prev_api_changes/api_changes_3.1.0.rst
diff --git a/doc/api/prev_api_changes/api_changes_3.1.0.rst b/doc/api/prev_api_changes/api_changes_3.1.0.rst
@@ -1,3 +1,6 @@
+API Changes for 3.1.0
+=====================
+
 API removals
 ------------
 
@@ -353,7 +356,7 @@ The following keyword arguments are deprecated:
   `~mpl_toolkits.mplot3d.axes3d.Axes3D.plot_surface` is deprecated. This was
   an unintended implementation detail with the same semantics as
   ``shade=False``. Please use the latter code instead.API removals
-````````````
+
 
 The following deprecated APIs were removed:
 
