Reorganize the developer docs. Most importantly, this adds a pull req…

…uest checklist.
matplotlib · pelson · Nov 20, 2012 · Nov 16, 2012 · Nov 16, 2012 · Nov 16, 2012
commit 8ec5b2c5346fe1c41564594cc9622444d8e703cb
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -46,6 +46,84 @@ statement, such as::
 
   .. include:: ../../TODO
 
+docstrings
+----------
+
+In addition to the "narrative" documentation described above,
+matplotlib also defines its API reference documentation in docstrings.
+For the most part, these are standard Python docstrings, but
+matplotlib also includes some features to better support documenting
+getters and setters.
+
+Matplotlib uses artist introspection 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 :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 (: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.  Matplotlib uses
+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.
+
+The functions :attr:`matplotlib.artist.kwdocd` and
+:func:`matplotlib.artist.kwdoc` to facilitate 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 :class:`~matplotlib.lines.Line2D`
+pass-through ``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
+
+      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 :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.
+There are some some manual hacks in this case, violating the
+"single entry point" requirement above -- see the
+``artist.kwdocd['Patch']`` setting in :mod:`matplotlib.patches`.
 
 .. _formatting-mpl-docs:
 
@@ -181,11 +259,6 @@ working with Sphinx in general. Here are a few additional things to keep in mind
 .. _`inline markup`: http://sphinx.pocoo.org/markup/inline.html
 .. _index: http://sphinx.pocoo.org/markup/para.html#index-generating-markup
 
-Docstrings
-----------
-
-In addition to the aforementioned formatting suggestions:
-
 * Please limit the text width of docstrings to 70 characters.
 
 * Keyword arguments should be described using a definition list.
@@ -195,7 +268,6 @@ In addition to the aforementioned formatting suggestions:
      arguments, there are a many cases where a table is used in place of a
      definition list for autogenerated sections of docstrings.
 
-
 Figures
 =======
 

diff --git a/doc/devel/gitwash/development_workflow.rst b/doc/devel/gitwash/development_workflow.rst
@@ -134,6 +134,9 @@ without interfering with the output from the comparison.  More detail?
 Note the three dots in the URL above (``master...my-new-feature``) and
 see :ref:`dot2-dot3`.
 
+It's a good idea to consult the :ref:`pull-request-checklist` to make
+sure your pull request is ready for merging.
+
 Asking for your changes to be merged into the main repo
 =======================================================
 

diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -13,9 +13,10 @@
    :maxdepth: 2
 
    coding_guide.rst
+   license.rst
    gitwash/index.rst
+   testing.rst
    documenting_mpl.rst
    release_guide.rst
    transformations.rst
    add_new_projection.rst
-   outline.rst
diff --git a/doc/devel/license.rst b/doc/devel/license.rst
@@ -0,0 +1,69 @@
+.. _license-discussion:
+
+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
+(see the Open Source Initiative `licenses page
+<http://www.opensource.org/licenses>`_ for details on individual
+licenses).  If it doesn't, you may consider contacting the author and
+asking them to relicense it.  GPL and LGPL code are not acceptable 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.  Non-BSD compatible licenses
+are acceptable in matplotlib toolkits (eg basemap), but make sure you
+clearly state the licenses you are using.
+
+Why BSD compatible?
+-------------------
+
+The two dominant license variants in the wild are GPL-style and
+BSD-style. There are countless other licenses that place specific
+restrictions on code reuse, but there is an important difference to be
+considered in the GPL and BSD variants.  The best known and perhaps
+most widely used license is the GPL, which in addition to granting you
+full rights to the source code including redistribution, carries with
+it an extra obligation. If you use GPL code in your own code, or link
+with it, your product must be released under a GPL compatible
+license. I.e., you are required to give the source code to other
+people and give them the right to redistribute it as well. Many of the
+most famous and widely used open source projects are released under
+the GPL, including linux, gcc, emacs and sage.
+
+The second major class are the BSD-style licenses (which includes MIT
+and the python PSF license). These basically allow you to do whatever
+you want with the code: ignore it, include it in your own open source
+project, include it in your proprietary product, sell it,
+whatever. python itself is released under a BSD compatible license, in
+the sense that, quoting from the PSF license page::
+
+    There is no GPL-like "copyleft" restriction. Distributing
+    binary-only versions of Python, modified or not, is allowed. There
+    is no requirement to release any of your source code. You can also
+    write extension modules for Python and provide them only in binary
+    form.
+
+Famous projects released under a BSD-style license in the permissive
+sense of the last paragraph are the BSD operating system, python and
+TeX.
+
+There are several reasons why early matplotlib developers selected a
+BSD compatible license. matplotlib is a python extension, and we
+choose a license that was based on the python license (BSD
+compatible).  Also, we wanted to attract as many users and developers
+as possible, and many software companies will not use GPL code in
+software they plan to distribute, even those that are highly committed
+to open source development, such as `enthought
+<http://enthought.com>`_, out of legitimate concern that use of the
+GPL will "infect" their code base by its viral nature. In effect, they
+want to retain the right to release some proprietary code. Companies
+and institutions who use matplotlib often make significant
+contributions, because they have the resources to get a job done, even
+a boring one. Two of the matplotlib backends (FLTK and WX) were
+contributed by private companies.  The final reason behind the
+licensing choice is compatibility with the other python extensions for
+scientific computing: ipython, numpy, scipy, the enthought tool suite
+and python itself are all distributed under BSD compatible licenses.