matplotlib
diff --git a/‎doc/devel/coding_guide.rst‎
Lines changed: 117 additions & 92 deletions b/‎doc/devel/coding_guide.rst‎
Lines changed: 117 additions & 92 deletions
@@ -18,7 +18,7 @@ Checking out the main source::
 Branch checkouts, eg the maintenance branch::
 
    svn co https://matplotlib.svn.sourceforge.net/svnroot/matplotlib/branches/\
-   v0_91_maint mpl91
+   v0_91_maint mpl91 --username=youruser --password=yourpass
 
 Committing changes
 ==================
@@ -27,26 +27,25 @@ 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
+  :file:`CHANGELOG`
+* if you change the API, please document it in :file:`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.
+* Are your changes python2.4 compatible?  We are still trying to
+  support 2.4, so avoid features new to 2.5
+* Can you pass :file:`examples/tests/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
+  :file:`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
+  :file:`MANIFEST.in`.  This file determines what goes into the source
   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:
+  If there is a bug on both that needs fixing, use `svnmerge.py
+  <http://www.orcaware.com/svn/wiki/Svnmerge.py>`_ to keep them in
+  sync.  The basic procedure is:
 
-  * install svnmerge.py in your PATH::
+  * install ``svnmerge.py`` in your PATH::
 
       wget http://svn.collab.net/repos/svn/trunk/contrib/client-side/\
       svnmerge/svnmerge.py
@@ -56,11 +55,22 @@ in mind.
     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
+       > svnmerge.py merge
 
-   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::
+    If you wish to merge only specific revisions (in an unusual
+    situation), do::
+
+       > svnmerge.py merge -rNNN1-NNN2
+
+    where the ``NNN`` are the revision numbers.  Ranges are also
+    acceptable.
+
+    The merge may have found some conflicts (code that must be
+    manually resolved).  Correct those conflicts, build matplotlib and
+    test your choices.
+
+    ``svnmerge.py`` automatically creates a file containing the commit
+    messages, so you are ready to make the commit::
 
        > svn commit -F svnmerge-commit-message.txt
 
@@ -71,7 +81,7 @@ Style Guide
 Importing and name spaces
 =========================
 
-For numpy, use::
+For `numpy <http://www.numpy.org>`_, use::
 
   import numpy as np
   a = np.array([1,2,3])
@@ -80,11 +90,11 @@ 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
+(The earlier recommendation, :samp:`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::
@@ -99,24 +109,25 @@ For matplotlib modules (or any other modules), use::
   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
+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
+coding guidelines for python written by Guido in `PEP 0008
+<http://www.python.org/dev/peps/pep-0008>`_, though we do not do this
 throughout.
 
-* functions and class methods: lower or lower_underscore_separated
+* functions and class methods: ``lower`` or
+  ``lower_underscore_separated``
 
-* attributes and variables: lower or lowerUpper
+* attributes and variables: ``lower`` or ``lowerUpper``
 
-* classes: Upper or MixedCase
+* classes: ``Upper`` or ``MixedCase``
 
 Personally, I prefer the shortest names that are still readable.
 
@@ -129,27 +140,32 @@ Please avoid spurious invisible spaces at the ends of lines.
 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.
+nothing to the left of the triple quotes.  The
+:func:`matplotlib.cbook.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.
+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++::
+noise in svn diffs.
+
+If you are an emacs user, the following in your ``.emacs`` will cause
+emacs to strip trailing white space upon saving for python, C and C++:
+
+.. code-block:: cl
 
   ; 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::
+for older versions of emacs (emacs<22) you need to do:
+
+.. code-block:: cl
 
   (add-hook 'python-mode-hook
             (lambda ()
@@ -160,34 +176,37 @@ 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::
+:func:`matplotlib.pylab.text`.  The definition of the pylab text
+function is a simple pass-through to
+:meth:`matplotlib.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__::
+:meth:`~matplotlib.axes.Axes.text` in simplified form looks like this,
+i.e., it just passes them on to :meth:`matplotlib.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::
+and :meth:`~matplotlib.text.Text.__init__` (again with liberties for
+illustration) just passes them on to the
+:meth:`matplotlib.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.
+``update`` does the work looking for methods named like
+``set_property`` if ``property`` is a keyword argument.  I.e., no one
+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
@@ -197,9 +216,10 @@ 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::
+rest, eg., I pop ``scalex`` and ``scaley`` in
+:meth:`~matplotlib.axes.Axes.plot` and assume the rest are
+:meth:`~matplotlib.lines.Line2D` keyword arguments.  As an example of
+a pop, passthrough usage, see :meth:`~matplotlib.axes.Axes.plot`::
 
   # in axes.py
   def plot(self, *args, **kwargs):
@@ -211,16 +231,17 @@ usage, see Axes.plot::
           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,
+The :mod:`matplotlib.cbook` function :func:`~matplotlib.cbook.popd` is rendered
+obsolete by the :func:`~dict.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::
+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
+:meth:`matplotlib.contour.ContourLabeler.clabel`::
 
   # in contour.py
   def clabel(self, *args, **kwargs):
@@ -238,51 +259,54 @@ 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::
+properties.  All properties that you want to support through ``setp``
+and ``getp`` should have a ``set_property`` and ``get_property``
+method in the :class:`~matplotlib.artist.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 :class:`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:
+Since matplotlib uses a lot of pass through ``kwargs``, eg. in every
+function that creates a line (:func:`~matplotlib.pyplot.plot`,
+:func:`~matplotlib.pyplot.semilogx`,
+:func:`~matplotlib.pyplot.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
+   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::
+I have added a :attr:`matplotlib.artist.kwdocd` and
+:func:`matplotlib.artist.kwdoc` to faciliate this.  They combine
+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 :mod:`matplotlib.lines`::
 
   # in lines.py
   artist.kwdocd['Line2D'] = artist.kwdoc(Line2D)
 
-Then in any function accepting Line2D passthrough kwargs, eg
-matplotlib.axes.Axes.plot::
+Then in any function accepting :class:`~matplotlib.lines.Line2D`
+passthrough ``kwargs``, eg. :meth:`matplotlib.axes.Axes.plot`::
 
   # in axes.py
   def plot(self, *args, **kwargs):
       """
       Some stuff omitted
-       
+
       The kwargs are Line2D properties:
       %(Line2D)s
 
@@ -294,13 +318,14 @@ matplotlib.axes.Axes.plot::
       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
+Note there is a problem for :class:`~matplotlib.artist.Artist`
+``__init__`` methods, eg. :meth:`matplotlib.patches.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
+``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
+before too long.
 
 ********
 Licenses
@@ -314,4 +339,4 @@ 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.
+you to distribute the license with it.