removed mpl_data link

svn path=/branches/v0_98_5_maint/; revision=6627

Author: jdh2358

CHANGELOG

@@ -1,3 +1,10 @@
+2008-12-15 Removed mpl_data symlink in docs.  On platforms that do not
+           support symlinks, these become copies, and the font files
+           are large, so the distro becomes unneccessarily bloaded.
+           Keeping the mpl_examples dir because relative links are
+           harder for the plot directive and the *.py files are not so
+           large. - JDH
+
 2008-12-15 Fix \$ in non-math text with usetex off.  Document
 differences between usetex on/off - MGD
 

doc/README.txt

@@ -27,9 +27,6 @@ python documentation system built on top of ReST.  This directory contains
 
 * sphinxext - Sphinx extensions for the mpl docs
 
-* mpl_data - a symbolic link to the matplotlib data for reference by
-  sphinx documentation
-
 * mpl_examples - a link to the matplotlib examples in case any
   documentation wants to literal include them
 

doc/devel/documenting_mpl.rst

@@ -271,25 +271,40 @@ Referring to mpl documents
 ==========================
 
 In the documentation, you may want to include to a document in the
-matplotlib src, e.g. a license file, an image file from `mpl-data`, or an
-example.  When you include these files, include them using a symbolic
-link from the documentation parent directory.  This way, if we
-relocate the mpl documentation directory, all of the internal pointers
-to files will not have to change, just the top level symlinks.  For
-example, In the top level doc directory we have symlinks pointing to
-the mpl `examples` and `mpl-data`::
-
-    home:~/mpl/doc2> ls -l mpl_*
-    mpl_data -> ../lib/matplotlib/mpl-data
-    mpl_examples -> ../examples
+matplotlib src, e.g. a license file or an image file from `mpl-data`,
+refer to it via a relative path from the document where the rst file
+resides, eg, in :file:`users/navigation_toolbar.rst`, we refer to the
+image icons with::
 
+    .. image:: ../../lib/matplotlib/mpl-data/images/subplots.png
 
 In the `users` subdirectory, if I want to refer to a file in the mpl-data
 directory, I use the symlink directory.  For example, from
 `customizing.rst`::
 
-   .. literalinclude:: ../mpl_data/matplotlibrc
+    .. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc
+
+On exception to this is when referring to the examples dir.  Relative
+paths are extremely confusing in the sphinx plot extensions, so
+without getting into the dirty details, it is easier to simply include
+a symlink to the files at the top doc level directory.  This way, API
+documents like :meth:`matplotlib.pyplot.plot` can refer to the
+examples in a known location.
+
+In the top level doc directory we have symlinks pointing to
+the mpl `examples`::
+
+    home:~/mpl/doc> ls -l mpl_*
+    mpl_examples -> ../examples
+
+So we can include plots from the examples dir using the symlink::
+
+    .. plot:: mpl_examples/pylab_examples/simple_plot.py
+
 
+We used to use a symlink for :file:`mpl-data` too, but the distro
+becomes very large on platforms that do not support links (eg the font
+files are duplicated and large)
 
 .. _internal-section-refs:
 

doc/make.py

@@ -41,7 +41,7 @@ def html():
     check_build()
     if not os.path.exists('examples/index.rst'):
         examples()
-    shutil.copy('mpl_data/matplotlibrc', '_static/matplotlibrc')
+    shutil.copy('../lib/matplotlib/mpl-data/matplotlibrc', '_static/matplotlibrc')
     #figs()
     if os.system('sphinx-build -b html -d build/doctrees . build/html'):
         raise SystemExit("Building HTML failed.")

doc/users/customizing.rst

@@ -67,4 +67,4 @@ A sample matplotlibrc file
 
     `(download) <../_static/matplotlibrc>`__
 
-.. literalinclude:: ../mpl_data/matplotlibrc
+.. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc

doc/users/navigation_toolbar.rst

@@ -9,11 +9,11 @@ All figure windows come with a navigation toolbar, which can be used
 to navigate through the data set.  Here is a description of each of
 the buttons at the bottom of the toolbar
 
-.. image:: ../mpl_data/images/home.png
+.. image:: ../../lib/matplotlib/mpl-data/images/home.png
 
-.. image:: ../mpl_data/images/back.png
+.. image:: ../../lib/matplotlib/mpl-data/images/back.png
 
-.. image:: ../mpl_data/images/forward.png
+.. image:: ../../lib/matplotlib/mpl-data/images/forward.png
 
 The ``Forward`` and ``Back`` buttons
     These are akin to the web browser forward and back buttons.  They
@@ -26,7 +26,7 @@ The ``Forward`` and ``Back`` buttons
     ``Back``, think web browser where data views are web pages.  Use
     the pan and zoom to rectangle to define new views.
 
-.. image:: ../mpl_data/images/move.png
+.. image:: ../../lib/matplotlib/mpl-data/images/move.png
 
 The ``Pan/Zoom`` button
     This button has two modes: pan and zoom.  Click the toolbar button
@@ -50,7 +50,7 @@ The ``Pan/Zoom`` button
     mouse button.  The radius scale can be zoomed in and out using the
     right mouse button.
 
-.. image:: ../mpl_data/images/zoom_to_rect.png
+.. image:: ../../lib/matplotlib/mpl-data/images/zoom_to_rect.png
 
 The ``Zoom-to-rectangle`` button
     Click this toolbar button to activate this mode.  Put your mouse
@@ -61,14 +61,14 @@ The ``Zoom-to-rectangle`` button
     with the right button, which will place your entire axes in the
     region defined by the zoom out rectangle.
 
-.. image:: ../mpl_data/images/subplots.png
+.. image:: ../../lib/matplotlib/mpl-data/images/subplots.png
 
 The ``Subplot-configuration`` button
     Use this tool to configure the parameters of the subplot: the
     left, right, top, bottom, space between the rows and space between
     the columns.
 
-.. image:: ../mpl_data/images/filesave.png
+.. image:: ../../lib/matplotlib/mpl-data/images/filesave.png
 
 The ``Save`` button
     Click this button to launch a file save dialog.  You can save
@@ -84,14 +84,14 @@ Command                            Keyboard Shortcut(s)
 ================================== ==============================================
 Home/Reset                         **h** or **r** or **home**
 Back                               **c** or **left arrow** or **backspace**
-Forward                            **v** or **right arrow** 
-Pan/Zoom                           **p**                                        
-Zoom-to-rect                       **o**                   
-Save                               **s**                   
+Forward                            **v** or **right arrow**
+Pan/Zoom                           **p**
+Zoom-to-rect                       **o**
+Save                               **s**
 Toggle fullscreen                  **f**
 Constrain pan/zoom to x axis       hold **x**
 Constrain pan/zoom to y axis       hold **y**
-Preserve aspect ratio              hold **CONTROL**     
+Preserve aspect ratio              hold **CONTROL**
 Toggle grid                        **g**
 Toggle y axis scale (log/linear)   **l**
 ================================== ==============================================