Merged revisions 6627,6629 via svnmerge from

https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/v0_98_5_maint

........
  r6627 | jdh2358 | 2008-12-16 06:44:09 -0800 (Tue, 16 Dec 2008) | 1 line
  
  removed mpl_data link
........
  r6629 | jdh2358 | 2008-12-16 08:13:07 -0800 (Tue, 16 Dec 2008) | 1 line
  
  applied Darren's sphinx patch, cleaned up some docstrings
........

svn path=/trunk/matplotlib/; revision=6630

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/api/api_changes.rst

@@ -260,7 +260,7 @@ The :class:`Polar` class has moved to :mod:`matplotlib.projections.polar`.
    `Axes.toggle_log_lineary()` has been removed.
 
 :mod:`matplotlib.artist`
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ============================================================ ============================================================
 Old method                                                   New method

doc/api/font_manager_api.rst

@@ -11,7 +11,7 @@ matplotlib font_manager
    :show-inheritance:
 
 :mod:`matplotlib.fontconfig_pattern`
-====================================
+========================================
 
 .. automodule:: matplotlib.fontconfig_pattern
    :members:

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/pyplots/plotmap.py

@@ -11,7 +11,7 @@
 # read in topo data (on a regular lat/lon grid)
 # longitudes go from 20 to 380.
 # you can get this data from matplolib svn matplotlib/htdocs/screenshots/data/
-datadir = '/home/jdhunter/python/svn/matplotlib/htdocs/screenshots/data/'
+datadir = '/home/jdhunter/python/svn/matplotlib/trunk/htdocs/screenshots/data/'
 if not os.path.exists(datadir):
     raise SystemExit('You need to download the data with svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/htdocs/screenshots/data/" and set the datadir variable in %s'%__file__)
 

doc/sphinxext/inheritance_diagram.py

@@ -39,8 +39,6 @@ class E(B): pass
     from md5 import md5
 
 from docutils.nodes import Body, Element
-from docutils.writers.html4css1 import HTMLTranslator
-from sphinx.latexwriter import LaTeXTranslator
 from docutils.parsers.rst import directives
 from sphinx.roles import xfileref_role
 
@@ -409,12 +407,9 @@ def run(self):
                                   inheritance_diagram_directive)
 
 def setup(app):
-    app.add_node(inheritance_diagram)
-
-    HTMLTranslator.visit_inheritance_diagram = \
-        visit_inheritance_diagram(html_output_graph)
-    HTMLTranslator.depart_inheritance_diagram = do_nothing
-
-    LaTeXTranslator.visit_inheritance_diagram = \
-        visit_inheritance_diagram(latex_output_graph)
-    LaTeXTranslator.depart_inheritance_diagram = do_nothing
+    app.add_node(inheritance_diagram,
+                 html=(visit_inheritance_diagram(html_output_graph),
+                       do_nothing))
+    app.add_node(inheritance_diagram,
+                 latex=(visit_inheritance_diagram(latex_output_graph),
+                        do_nothing))

doc/sphinxext/mathmpl.py

@@ -6,8 +6,6 @@
 
 from docutils import nodes
 from docutils.parsers.rst import directives
-from docutils.writers.html4css1 import HTMLTranslator
-from sphinx.latexwriter import LaTeXTranslator
 import warnings
 
 # Define LaTeX math node:
@@ -69,8 +67,6 @@ def visit_latex_math_html(self, node):
         self.body.append(latex2html(node, source))
     def depart_latex_math_html(self, node):
             pass
-    HTMLTranslator.visit_latex_math = visit_latex_math_html
-    HTMLTranslator.depart_latex_math = depart_latex_math_html
 
     # Add visit/depart methods to LaTeX-Translator:
     def visit_latex_math_latex(self, node):
@@ -83,8 +79,13 @@ def visit_latex_math_latex(self, node):
                               '\\end{equation}'])
     def depart_latex_math_latex(self, node):
             pass
-    LaTeXTranslator.visit_latex_math = visit_latex_math_latex
-    LaTeXTranslator.depart_latex_math = depart_latex_math_latex
+
+    app.add_node(latex_math, html=(visit_latex_math_html,
+                                   depart_latex_math_html))
+    app.add_node(latex_math, latex=(visit_latex_math_latex,
+                                    depart_latex_math_latex))
+    app.add_role('math', math_role)
+
 
 from matplotlib import rcParams
 from matplotlib.mathtext import MathTextParser

doc/sphinxext/only_directives.py

@@ -4,8 +4,6 @@
 #
 
 from docutils.nodes import Body, Element
-from docutils.writers.html4css1 import HTMLTranslator
-from sphinx.latexwriter import LaTeXTranslator
 from docutils.parsers.rst import directives
 
 class html_only(Body, Element):
@@ -63,9 +61,6 @@ class LatexOnlyDirective(OnlyDirective):
     directives.register_directive('latexonly', LatexOnlyDirective)
 
 def setup(app):
-    app.add_node(html_only)
-    app.add_node(latex_only)
-
     # Add visit/depart methods to HTML-Translator:
     def visit_perform(self, node):
         pass
@@ -76,12 +71,7 @@ def visit_ignore(self, node):
     def depart_ignore(self, node):
         node.children = []
 
-    HTMLTranslator.visit_html_only = visit_perform
-    HTMLTranslator.depart_html_only = depart_perform
-    HTMLTranslator.visit_latex_only = visit_ignore
-    HTMLTranslator.depart_latex_only = depart_ignore
-
-    LaTeXTranslator.visit_html_only = visit_ignore
-    LaTeXTranslator.depart_html_only = depart_ignore
-    LaTeXTranslator.visit_latex_only = visit_perform
-    LaTeXTranslator.depart_latex_only = depart_perform
+    app.add_node(html_only, html=(visit_perform, depart_perform))
+    app.add_node(html_only, latex=(visit_ignore, depart_ignore))
+    app.add_node(latex_only, latex=(visit_perform, depart_perform))
+    app.add_node(latex_only, html=(visit_ignore, depart_ignore))