Menu
▾
▴
SF.net SVN: matplotlib: [5226] trunk/matplotlib/doc
|
From: <ds...@us...> - 2008-05-23 14:37:59
|
Revision: 5226
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5226&view=rev
Author: dsdale
Date: 2008-05-23 07:37:51 -0700 (Fri, 23 May 2008)
Log Message:
-----------
use mathpng extension rather than mathml
generate html rather than xml
Modified Paths:
--------------
trunk/matplotlib/doc/api_reference/conf.py
trunk/matplotlib/doc/api_reference/make.py
trunk/matplotlib/doc/users_guide/coding_guide.txt
trunk/matplotlib/doc/users_guide/conf.py
Added Paths:
-----------
trunk/matplotlib/doc/sphinxext/mathpng.py
Removed Paths:
-------------
trunk/matplotlib/doc/CODING_GUIDE
Deleted: trunk/matplotlib/doc/CODING_GUIDE
===================================================================
--- trunk/matplotlib/doc/CODING_GUIDE 2008-05-23 14:13:16 UTC (rev 5225)
+++ trunk/matplotlib/doc/CODING_GUIDE 2008-05-23 14:37:51 UTC (rev 5226)
@@ -1,317 +0,0 @@
-***************
-Version Control
-***************
-
-svn checkouts
-=============
-
-Checking out everything in the trunk (matplotlib and toolkits)::
-
- svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk \
- matplotlib --username=youruser --password=yourpass
-
-Checking out the main source::
-
- svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/\
- matplotlib matplotlib --username=youruser --password=yourpass
-
-Branch checkouts, eg the maintenance branch::
-
- svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/\
- v0_91_maint mplv0_91_maint
-
-Committing changes
-==================
-
-When committing changes to matplotlib, there are a few things to bear
-in mind.
-
-* if your changes are non-trivial, please make an entry in the
- CHANGELOG
-* if you change the API, please document it in API_CHANGES, and
- consider posting to mpl-devel
-* Are your changes python2.3 compatible? We are still trying to
- support 2.3, so avoid 2.4 only features like decorators until we
- remove 2.3 support
-* Can you pass examples/backend_driver.py? This is our poor man's
- unit test.
-* If you have altered extension code, do you pass
- unit/memleak_hawaii.py?
-* if you have added new files or directories, or reorganized
- existing ones, are the new files included in the match patterns in
- MANIFEST.in. This file determines what goes into the src
- distribution of the mpl build.
-* Keep the maintenance branch and trunk in sync where it makes sense.
- If there is a bug on both that needs fixing, use svnmerge.py to
- keep them in sync. http://www.orcaware.com/svn/wiki/Svnmerge.py. The
- basic procedure is:
-
- * install svnmerge.py in your PATH::
-
- wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/\
- svnmerge/svnmerge.py
-
- * get a svn copy of the maintenance branch and the trunk (see above)
- * Michael advises making the change on the branch and committing
- it. Make sure you svn upped on the trunk and have no local
- modifications, and then from the svn trunk do::
-
- > svnmerge.py merge -rNNN1,NNN2
-
- where the NNN* are the revision numbers. Ranges arealso acceptable.
- svnmergy.py automatically creates a file containing the commit messages,
- so you are ready to make the commit::
-
- > svn commit -F svnmerge-commit-message.txt
-
-***********
-Style Guide
-***********
-
-Importing and name spaces
-=========================
-
-For numpy, use::
-
- import numpy as np
- a = np.array([1,2,3])
-
-For masked arrays, use::
-
- from numpy import ma
-
-(The earlier recommendation, 'import matplotlib.numerix.npyma as ma',
-was needed temporarily during the development of the maskedarray
-implementation as a separate package. As of numpy 1.1, it replaces the
-old implementation. Note: "from numpy import ma" works with numpy < 1.1
-*and* with numpy >= 1.1. "import numpy.ma as ma" works *only* with
-numpy >= 1.1, so for now we must not use it.)
-
-For matplotlib main module, use::
-
- import matplotlib as mpl
- mpl.rcParams['xtick.major.pad'] = 6
-
-For matplotlib modules (or any other modules), use::
-
- import matplotlib.cbook as cbook
-
- if cbook.iterable(z):
- pass
-
-We prefer this over the equivalent 'from matplotlib import cbook'
-because the latter is ambiguous whether cbook is a module or a
-function to the new developer. The former makes it explcit that
-you are importing a module or package.
-
-Naming, spacing, and formatting conventions
-===========================================
-
-In general, we want to hew as closely as possible to the standard
-coding guidelines for python written by Guido in
-http://www.python.org/dev/peps/pep-0008, though we do not do this
-throughout.
-
-* functions and class methods: lower or lower_underscore_separated
-
-* attributes and variables: lower or lowerUpper
-
-* classes: Upper or MixedCase
-
-Personally, I prefer the shortest names that are still readable.
-
-Also, use an editor that does not put tabs in files. Four spaces
-should be used for indentation everywhere and if there is a file with
-tabs or more or less spaces it is a bug -- please fix it.
-
-Please avoid spurious invisible spaces at the ends of lines.
-(Tell your editor to strip whitespace from line ends when saving
-a file.)
-
-Keep docstrings uniformly indented as in the example below, with
-nothing to the left of the triple quotes. The dedent() function
-is needed to remove excess indentation only if something will be
-interpolated into the docstring, again as in the example above.
-
-Limit line length to 80 characters. If a logical line needs to be
-longer, use parentheses to break it; do not use an escaped
-newline. It may be preferable to use a temporary variable
-to replace a single long line with two shorter and more
-readable lines.
-
-Please do not commit lines with trailing white space, as it causes
-noise in svn diffs. If you are an emacs user, the following in your
-.emacs will cause emacs to strip trailing white space on save for
-python, C and C++::
-
- ; and similarly for c++-mode-hook and c-mode-hook
- (add-hook 'python-mode-hook
- (lambda ()
- (add-hook 'write-file-functions 'delete-trailing-whitespace)))
-
-for older versions of emacs (emacs<22) you need to do::
-
- (add-hook 'python-mode-hook
- (lambda ()
- (add-hook 'local-write-file-hooks 'delete-trailing-whitespace)))
-
-Keyword argument processing
-===========================
-
-Matplotlib makes extensive use of ``**kwargs`` for pass through
-customizations from one function to another. A typical example is in
-pylab.text, The definition of the pylab text function is a simple
-pass-through to axes.Axes.text::
-
- # in pylab.py
- def text(*args, **kwargs):
- ret = gca().text(*args, **kwargs)
- draw_if_interactive()
- return ret
-
-axes.Axes.text in simplified form looks like this, ie it just passes
-them on to text.Text.__init__::
-
- # in axes.py
- def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
- t = Text(x=x, y=y, text=s, **kwargs)
-
-and Text.__init__ (again with liberties for illustration) just passes
-them on to the artist.Artist.update method::
-
- # in text.py
- def __init__(self, x=0, y=0, text='', **kwargs):
- Artist.__init__(self)
- self.update(kwargs)
-
-'update' does the work looking for methods named like 'set_property'
-if 'property' is a keyword argument. Ie, noone looks at the keywords,
-they just get passed through the API to the artist constructor which
-looks for suitably named methods and calls them with the value.
-
-As a general rule, the use of ``**kwargs`` should be reserved for
-pass-through keyword arguments, as in the examaple above. If I intend
-for all the keyword args to be used in some function and not passed
-on, I just use the key/value keyword args in the function definition
-rather than the ``**kwargs`` idiom.
-
-In some cases I want to consume some keys and pass through the others,
-in which case I pop the ones I want to use locally and pass on the
-rest, eg I pop scalex and scaley in Axes.plot and assume the rest are
-Line2D keyword arguments. As an example of a pop, passthrough
-usage, see Axes.plot::
-
- # in axes.py
- def plot(self, *args, **kwargs):
- scalex = kwargs.pop('scalex', True)
- scaley = kwargs.pop('scaley', True)
- if not self._hold: self.cla()
- lines = []
- for line in self._get_lines(*args, **kwargs):
- self.add_line(line)
- lines.append(line)
-
-The matplotlib.cbook function popd() is rendered
-obsolete by the pop() dictionary method introduced in Python 2.3,
-so it should not be used for new code.
-
-Note there is a use case when kwargs are meant to be used locally in
-the function (not passed on), but you still need the ``**kwargs`` idiom.
-That is when you want to use ``*args`` to allow variable numbers of
-non-keyword args. In this case, python will not allow you to use
-named keyword args after the ``*args`` usage, so you will be forced to use
-``**kwargs``. An example is matplotlib.contour.ContourLabeler.clabel::
-
- # in contour.py
- def clabel(self, *args, **kwargs):
- fontsize = kwargs.get('fontsize', None)
- inline = kwargs.get('inline', 1)
- self.fmt = kwargs.get('fmt', '%1.3f')
- colors = kwargs.get('colors', None)
- if len(args) == 0:
- levels = self.levels
- indices = range(len(self.levels))
- elif len(args) == 1:
- ...etc...
-
-Documentation and Docstrings
-============================
-
-matplotlib uses artist instrospection of docstrings to support
-properties. All properties that you want to support through setp and
-getp should have a set_property and get_property method in the Artist
-class. Yes, this is not ideal given python properties or enthought
-traits, but it is a historical legacy for now. The setter methods use
-the docstring with the ACCEPTS token to indicate the type of argument
-the method accepts. Eg in matplotlib.lines.Line2D::
-
- # in lines.py
- def set_linestyle(self, linestyle):
- """
- Set the linestyle of the line
-
- ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
- """
-
-Since matplotlib uses a lot of pass through kwargs, eg in every
-function that creates a line (plot, semilogx, semilogy, etc...), it
-can be difficult for the new user to know which kwargs are supported.
-I have developed a docstring interpolation scheme to support
-documentation of every function that takes a ``**kwargs``. The
-requirements are:
-
-1. single point of configuration so changes to the properties don't
- require multiple docstring edits
-
-2. as automated as possible so that as properties change the docs
- are updated automagically.
-
-I have added a matplotlib.artist.kwdocd and kwdoc() to faciliate this.
-They combines python string interpolation in the docstring with the
-matplotlib artist introspection facility that underlies setp and getp.
-The kwdocd is a single dictionary that maps class name to a docstring
-of kwargs. Here is an example from matplotlib.lines::
-
- # in lines.py
- artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
-
-Then in any function accepting Line2D passthrough kwargs, eg
-matplotlib.axes.Axes.plot::
-
- # in axes.py
- def plot(self, *args, **kwargs):
- """
- Some stuff omitted
-
- The kwargs are Line2D properties:
- %(Line2D)s
-
- kwargs scalex and scaley, if defined, are passed on
- to autoscale_view to determine whether the x and y axes are
- autoscaled; default True. See Axes.autoscale_view for more
- information
- """
- pass
- plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd
-
-Note there is a problem for Artist __init__ methods, eg Patch.__init__
-which supports Patch kwargs, since the artist inspector cannot work
-until the class is fully defined and we can't modify the
-Patch.__init__.__doc__ docstring outside the class definition. I have
-made some manual hacks in this case which violates the "single entry
-point" requirement above; hopefully we'll find a more elegant solution
-before too long
-
-********
-Licenses
-********
-
-Matplotlib only uses BSD compatible code. If you bring in code from
-another project make sure it has a PSF, BSD, MIT or compatible
-license. If not, you may consider contacting the author and asking
-them to relicense it. GPL and LGPL code are not acceptible in the
-main code base, though we are considering an alternative way of
-distributing L/GPL code through an separate channel, possibly a
-toolkit. If you include code, make sure you include a copy of that
-code's license in the license directory if the code's license requires
-you to distribute the license with it.
\ No newline at end of file
Modified: trunk/matplotlib/doc/api_reference/conf.py
===================================================================
--- trunk/matplotlib/doc/api_reference/conf.py 2008-05-23 14:13:16 UTC (rev 5225)
+++ trunk/matplotlib/doc/api_reference/conf.py 2008-05-23 14:37:51 UTC (rev 5226)
@@ -93,7 +93,7 @@
# If nonempty, this is the file name suffix for generated HTML files. The
# default is ``".html"``.
-html_file_suffix = '.xml'
+#html_file_suffix = '.xhtml'
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
Modified: trunk/matplotlib/doc/api_reference/make.py
===================================================================
--- trunk/matplotlib/doc/api_reference/make.py 2008-05-23 14:13:16 UTC (rev 5225)
+++ trunk/matplotlib/doc/api_reference/make.py 2008-05-23 14:37:51 UTC (rev 5226)
@@ -15,7 +15,7 @@
pass
def figs():
- os.system('cd source/figures/ && python make.py')
+ os.system('cd figures/ && python make.py')
def html():
check_build()
Added: trunk/matplotlib/doc/sphinxext/mathpng.py
===================================================================
--- trunk/matplotlib/doc/sphinxext/mathpng.py (rev 0)
+++ trunk/matplotlib/doc/sphinxext/mathpng.py 2008-05-23 14:37:51 UTC (rev 5226)
@@ -0,0 +1,107 @@
+import os
+try:
+ from hashlib import md5
+except ImportError:
+ from md5 import md5
+
+from docutils import nodes
+from docutils.writers.html4css1 import HTMLTranslator
+from sphinx.latexwriter import LaTeXTranslator
+
+# Define LaTeX math node:
+class latex_math(nodes.General, nodes.Element):
+ pass
+
+def math_role(role, rawtext, text, lineno, inliner,
+ options={}, content=[]):
+ i = rawtext.find('`')
+ latex = rawtext[i+1:-1]
+ node = latex_math(rawtext)
+ node['latex'] = latex
+ return [node], []
+
+
+try:
+ from docutils.parsers.rst import Directive
+except ImportError:
+ # Register directive the old way:
+ from docutils.parsers.rst.directives import _directives
+ def math_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ latex = ''.join(content)
+ node = latex_math(block_text)
+ node['latex'] = latex
+ return [node]
+ math_directive.arguments = None
+ math_directive.options = {}
+ math_directive.content = 1
+ _directives['math'] = math_directive
+else:
+ class math_directive(Directive):
+ has_content = True
+ def run(self):
+ latex = ' '.join(self.content)
+ node = latex_math(self.block_text)
+ node['latex'] = latex
+ return [node]
+ from docutils.parsers.rst import directives
+ directives.register_directive('math', math_directive)
+
+def setup(app):
+ app.add_node(latex_math)
+ app.add_role('math', math_role)
+
+ # Add visit/depart methods to HTML-Translator:
+ def visit_latex_math_html(self, node):
+ source = self.document.attributes['source']
+ 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):
+ inline = isinstance(node.parent, nodes.TextElement)
+ if inline:
+ self.body.append('$%s$' % node['latex'])
+ else:
+ self.body.extend(['\\begin{equation}',
+ node['latex'],
+ '\\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
+
+from os.path import isfile
+# LaTeX to HTML translation stuff:
+def latex2html(node, source):
+ inline = isinstance(node.parent, nodes.TextElement)
+ latex = node['latex']
+ print latex
+ name = 'math-' + md5(latex).hexdigest()[-10:]
+ if not isfile('_static/%s.png' % name):
+ f = open('math.tex', 'w')
+ f.write(r"""\documentclass[12pt]{article}
+ \pagestyle{empty}
+ \begin{document}""")
+ if inline:
+ f.write('$%s$' % latex)
+ else:
+ f.write(r'\[ %s \]' % latex)
+ f.write('\end{document}')
+ f.close()
+ os.system('latex --interaction=nonstopmode math.tex > /dev/null')
+ os.system('dvipng -bgTransparent -Ttight --noghostscript -l10 ' +
+ '-o _static/%s.png math.dvi > /dev/null' % name)
+ path = source.split('/doc/')[-1].count('/') * '../' + '_static'
+ if inline and '_' in latex:
+ align = 'align="absmiddle" '
+ else:
+ align = ''
+ if inline:
+ cls = ''
+ else:
+ cls = 'class="center" '
+ return '<img src="%s/%s.png" %s%s/>' % (path, name, align, cls)
Property changes on: trunk/matplotlib/doc/sphinxext/mathpng.py
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: trunk/matplotlib/doc/users_guide/coding_guide.txt
===================================================================
--- trunk/matplotlib/doc/users_guide/coding_guide.txt 2008-05-23 14:13:16 UTC (rev 5225)
+++ trunk/matplotlib/doc/users_guide/coding_guide.txt 2008-05-23 14:37:51 UTC (rev 5226)
@@ -1,3 +1,317 @@
+***************
+Version Control
+***************
-.. include:: ../../CODING_GUIDE
+svn checkouts
+=============
+Checking out everything in the trunk (matplotlib and toolkits)::
+
+ svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk \
+ matplotlib --username=youruser --password=yourpass
+
+Checking out the main source::
+
+ svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/trunk/\
+ matplotlib matplotlib --username=youruser --password=yourpass
+
+Branch checkouts, eg the maintenance branch::
+
+ svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/\
+ v0_91_maint mplv0_91_maint
+
+Committing changes
+==================
+
+When committing changes to matplotlib, there are a few things to bear
+in mind.
+
+* if your changes are non-trivial, please make an entry in the
+ CHANGELOG
+* if you change the API, please document it in API_CHANGES, and
+ consider posting to mpl-devel
+* Are your changes python2.3 compatible? We are still trying to
+ support 2.3, so avoid 2.4 only features like decorators until we
+ remove 2.3 support
+* Can you pass examples/backend_driver.py? This is our poor man's
+ unit test.
+* If you have altered extension code, do you pass
+ unit/memleak_hawaii.py?
+* if you have added new files or directories, or reorganized
+ existing ones, are the new files included in the match patterns in
+ MANIFEST.in. This file determines what goes into the src
+ distribution of the mpl build.
+* Keep the maintenance branch and trunk in sync where it makes sense.
+ If there is a bug on both that needs fixing, use svnmerge.py to
+ keep them in sync. http://www.orcaware.com/svn/wiki/Svnmerge.py. The
+ basic procedure is:
+
+ * install svnmerge.py in your PATH::
+
+ wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/\
+ svnmerge/svnmerge.py
+
+ * get a svn copy of the maintenance branch and the trunk (see above)
+ * Michael advises making the change on the branch and committing
+ it. Make sure you svn upped on the trunk and have no local
+ modifications, and then from the svn trunk do::
+
+ > svnmerge.py merge -rNNN1,NNN2
+
+ where the NNN* are the revision numbers. Ranges arealso acceptable.
+ svnmergy.py automatically creates a file containing the commit messages,
+ so you are ready to make the commit::
+
+ > svn commit -F svnmerge-commit-message.txt
+
+***********
+Style Guide
+***********
+
+Importing and name spaces
+=========================
+
+For numpy, use::
+
+ import numpy as np
+ a = np.array([1,2,3])
+
+For masked arrays, use::
+
+ from numpy import ma
+
+(The earlier recommendation, 'import matplotlib.numerix.npyma as ma',
+was needed temporarily during the development of the maskedarray
+implementation as a separate package. As of numpy 1.1, it replaces the
+old implementation. Note: "from numpy import ma" works with numpy < 1.1
+*and* with numpy >= 1.1. "import numpy.ma as ma" works *only* with
+numpy >= 1.1, so for now we must not use it.)
+
+For matplotlib main module, use::
+
+ import matplotlib as mpl
+ mpl.rcParams['xtick.major.pad'] = 6
+
+For matplotlib modules (or any other modules), use::
+
+ import matplotlib.cbook as cbook
+
+ if cbook.iterable(z):
+ pass
+
+We prefer this over the equivalent 'from matplotlib import cbook'
+because the latter is ambiguous whether cbook is a module or a
+function to the new developer. The former makes it explcit that
+you are importing a module or package.
+
+Naming, spacing, and formatting conventions
+===========================================
+
+In general, we want to hew as closely as possible to the standard
+coding guidelines for python written by Guido in
+http://www.python.org/dev/peps/pep-0008, though we do not do this
+throughout.
+
+* functions and class methods: lower or lower_underscore_separated
+
+* attributes and variables: lower or lowerUpper
+
+* classes: Upper or MixedCase
+
+Personally, I prefer the shortest names that are still readable.
+
+Also, use an editor that does not put tabs in files. Four spaces
+should be used for indentation everywhere and if there is a file with
+tabs or more or less spaces it is a bug -- please fix it.
+
+Please avoid spurious invisible spaces at the ends of lines.
+(Tell your editor to strip whitespace from line ends when saving
+a file.)
+
+Keep docstrings uniformly indented as in the example below, with
+nothing to the left of the triple quotes. The dedent() function
+is needed to remove excess indentation only if something will be
+interpolated into the docstring, again as in the example above.
+
+Limit line length to 80 characters. If a logical line needs to be
+longer, use parentheses to break it; do not use an escaped
+newline. It may be preferable to use a temporary variable
+to replace a single long line with two shorter and more
+readable lines.
+
+Please do not commit lines with trailing white space, as it causes
+noise in svn diffs. If you are an emacs user, the following in your
+.emacs will cause emacs to strip trailing white space on save for
+python, C and C++::
+
+ ; and similarly for c++-mode-hook and c-mode-hook
+ (add-hook 'python-mode-hook
+ (lambda ()
+ (add-hook 'write-file-functions 'delete-trailing-whitespace)))
+
+for older versions of emacs (emacs<22) you need to do::
+
+ (add-hook 'python-mode-hook
+ (lambda ()
+ (add-hook 'local-write-file-hooks 'delete-trailing-whitespace)))
+
+Keyword argument processing
+===========================
+
+Matplotlib makes extensive use of ``**kwargs`` for pass through
+customizations from one function to another. A typical example is in
+pylab.text, The definition of the pylab text function is a simple
+pass-through to axes.Axes.text::
+
+ # in pylab.py
+ def text(*args, **kwargs):
+ ret = gca().text(*args, **kwargs)
+ draw_if_interactive()
+ return ret
+
+axes.Axes.text in simplified form looks like this, ie it just passes
+them on to text.Text.__init__::
+
+ # in axes.py
+ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
+ t = Text(x=x, y=y, text=s, **kwargs)
+
+and Text.__init__ (again with liberties for illustration) just passes
+them on to the artist.Artist.update method::
+
+ # in text.py
+ def __init__(self, x=0, y=0, text='', **kwargs):
+ Artist.__init__(self)
+ self.update(kwargs)
+
+'update' does the work looking for methods named like 'set_property'
+if 'property' is a keyword argument. Ie, noone looks at the keywords,
+they just get passed through the API to the artist constructor which
+looks for suitably named methods and calls them with the value.
+
+As a general rule, the use of ``**kwargs`` should be reserved for
+pass-through keyword arguments, as in the examaple above. If I intend
+for all the keyword args to be used in some function and not passed
+on, I just use the key/value keyword args in the function definition
+rather than the ``**kwargs`` idiom.
+
+In some cases I want to consume some keys and pass through the others,
+in which case I pop the ones I want to use locally and pass on the
+rest, eg I pop scalex and scaley in Axes.plot and assume the rest are
+Line2D keyword arguments. As an example of a pop, passthrough
+usage, see Axes.plot::
+
+ # in axes.py
+ def plot(self, *args, **kwargs):
+ scalex = kwargs.pop('scalex', True)
+ scaley = kwargs.pop('scaley', True)
+ if not self._hold: self.cla()
+ lines = []
+ for line in self._get_lines(*args, **kwargs):
+ self.add_line(line)
+ lines.append(line)
+
+The matplotlib.cbook function popd() is rendered
+obsolete by the pop() dictionary method introduced in Python 2.3,
+so it should not be used for new code.
+
+Note there is a use case when kwargs are meant to be used locally in
+the function (not passed on), but you still need the ``**kwargs`` idiom.
+That is when you want to use ``*args`` to allow variable numbers of
+non-keyword args. In this case, python will not allow you to use
+named keyword args after the ``*args`` usage, so you will be forced to use
+``**kwargs``. An example is matplotlib.contour.ContourLabeler.clabel::
+
+ # in contour.py
+ def clabel(self, *args, **kwargs):
+ fontsize = kwargs.get('fontsize', None)
+ inline = kwargs.get('inline', 1)
+ self.fmt = kwargs.get('fmt', '%1.3f')
+ colors = kwargs.get('colors', None)
+ if len(args) == 0:
+ levels = self.levels
+ indices = range(len(self.levels))
+ elif len(args) == 1:
+ ...etc...
+
+Documentation and Docstrings
+============================
+
+matplotlib uses artist instrospection of docstrings to support
+properties. All properties that you want to support through setp and
+getp should have a set_property and get_property method in the Artist
+class. Yes, this is not ideal given python properties or enthought
+traits, but it is a historical legacy for now. The setter methods use
+the docstring with the ACCEPTS token to indicate the type of argument
+the method accepts. Eg in matplotlib.lines.Line2D::
+
+ # in lines.py
+ def set_linestyle(self, linestyle):
+ """
+ Set the linestyle of the line
+
+ ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
+ """
+
+Since matplotlib uses a lot of pass through kwargs, eg in every
+function that creates a line (plot, semilogx, semilogy, etc...), it
+can be difficult for the new user to know which kwargs are supported.
+I have developed a docstring interpolation scheme to support
+documentation of every function that takes a ``**kwargs``. The
+requirements are:
+
+1. single point of configuration so changes to the properties don't
+ require multiple docstring edits
+
+2. as automated as possible so that as properties change the docs
+ are updated automagically.
+
+I have added a matplotlib.artist.kwdocd and kwdoc() to faciliate this.
+They combines python string interpolation in the docstring with the
+matplotlib artist introspection facility that underlies setp and getp.
+The kwdocd is a single dictionary that maps class name to a docstring
+of kwargs. Here is an example from matplotlib.lines::
+
+ # in lines.py
+ artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
+
+Then in any function accepting Line2D passthrough kwargs, eg
+matplotlib.axes.Axes.plot::
+
+ # in axes.py
+ def plot(self, *args, **kwargs):
+ """
+ Some stuff omitted
+
+ The kwargs are Line2D properties:
+ %(Line2D)s
+
+ kwargs scalex and scaley, if defined, are passed on
+ to autoscale_view to determine whether the x and y axes are
+ autoscaled; default True. See Axes.autoscale_view for more
+ information
+ """
+ pass
+ plot.__doc__ = cbook.dedent(plot.__doc__) % artist.kwdocd
+
+Note there is a problem for Artist __init__ methods, eg Patch.__init__
+which supports Patch kwargs, since the artist inspector cannot work
+until the class is fully defined and we can't modify the
+Patch.__init__.__doc__ docstring outside the class definition. I have
+made some manual hacks in this case which violates the "single entry
+point" requirement above; hopefully we'll find a more elegant solution
+before too long
+
+********
+Licenses
+********
+
+Matplotlib only uses BSD compatible code. If you bring in code from
+another project make sure it has a PSF, BSD, MIT or compatible
+license. If not, you may consider contacting the author and asking
+them to relicense it. GPL and LGPL code are not acceptible in the
+main code base, though we are considering an alternative way of
+distributing L/GPL code through an separate channel, possibly a
+toolkit. If you include code, make sure you include a copy of that
+code's license in the license directory if the code's license requires
+you to distribute the license with it.
\ No newline at end of file
Modified: trunk/matplotlib/doc/users_guide/conf.py
===================================================================
--- trunk/matplotlib/doc/users_guide/conf.py 2008-05-23 14:13:16 UTC (rev 5225)
+++ trunk/matplotlib/doc/users_guide/conf.py 2008-05-23 14:37:51 UTC (rev 5226)
@@ -93,7 +93,7 @@
# If nonempty, this is the file name suffix for generated HTML files. The
# default is ``".html"``.
-html_file_suffix = '.xml'
+#html_file_suffix = '.xhtml'
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
