DOC: add explanation in writing docs

jklymak · jklymak · commit 75ba6be59fc7 · 2021-02-06T13:18:04.000-08:00
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -888,6 +888,42 @@ should ideally be named similar to :file:`imshow_mynewexample.py`.
 Miscellaneous
 =============
 
+Moving documentation
+--------------------
+
+Sometimes it is desirable to move or consolidate documentation.  With no
+action this will lead to links either going dead (404) or pointing to old
+versions of the documentation.  Preferable is to make a redirect on the
+new page that refers to the old page.  This will make the old page, but it
+will have an html refresh that immediately redirects the viewer to the new
+page.
+
+So, for example we move ``/doc/topic/old_info.rst`` to
+``/doc/topic/new_info.rst``.  We make remove ``/doc/topic/old_info.rst`` and
+in ``/doc/topic/new_info.rst`` we insert a redirect (probably near the
+top of the file to make it noticeable)
+
+.. code-block:: rst
+
+   .. redirect-from:: /topic/old_info
+
+In the built docs this will yield an html file
+``/build/html/topic/old_info.html`` that has a refresh to ``new_info.html``.
+If the two files are in different subdirectories:
+
+.. code-block:: rst
+
+   .. redirect-from:: /old_topic/old_info2
+
+will yield an html file ``/build/html/old_topic/old_info2.html`` that has a
+(relative) refresh to ``../topic/new_info.html``.
+
+Use the  full path for this directive, relative to the doc root at
+``http://matplotlib.org/stable/``.  So ``/old_topic/old_info2`` would be
+found by users at ``http://matplotlib.org/stable/old_topic/old_info2``.
+Do not use relative links.
+
+
 Adding animations
 -----------------
 
