Releasing 0.5.12.

Fix a few documentation warts.
Added changelog into RST documentation.
Restored glymur.lib.openjp2.*_v3 functions removed in 0.5.11

docs/source/conf.py

@@ -78,7 +78,7 @@ copyright = u'2013, John Evans'
 # The short X.Y version.
 version = '0.5'
 # The full version, including alpha/beta/rc tags.
-release = '0.5.11'
+release = '0.5.12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/detailed_installation.rst

@@ -1,20 +1,21 @@
 ----------------------------------
 Advanced Installation Instructions
 ----------------------------------
-Most users won't need to read this!  You've been warned...
 
 ''''''''''''''''''''''
 Glymur Configuration
 ''''''''''''''''''''''
 
 The default glymur installation process relies upon OpenJPEG being
-properly installed on your system as a shared library.  You need
-at least version 1.5 in order to read and write JPEG 2000 files.
+properly installed on your system as a shared library.  If you have OpenJPEG
+installed through your system's package manager on linux or if you use MacPorts
+on the mac, you are probably already set to go.  But if you have OpenJPEG 
+installed into a non-standard place or if you use windows, then read on.
 
 Glymur uses ctypes to access the openjp2/openjpeg libraries, and
 because ctypes accesses libraries in a platform-dependent manner,
 it is recommended that if you compile and install OpenJPEG into a
-non-standard location,  you should create a configuration file to
+non-standard location,  you should then create a configuration file to
 help Glymur properly find the openjpeg or openjp2 libraries (linux
 users or macports users don't need to bother with this if you are
 using OpenJPEG as provided by your package manager).  The configuration

docs/source/how_do_i.rst

@@ -68,10 +68,11 @@ The **append** method can add an XML box as shown below::
 
 ... add metadata in a more general fashion?
 ===========================================
-An existing raw codestream (or JP2 file) can be wrapped (re-wrapped) in a 
-user-defined set of JP2 boxes.  To get just a minimal JP2 jacket on the 
-codestream provided by `goodstuff.j2k` (a file consisting of a raw codestream),
-you can use the **wrap** method with no box argument: ::
+An existing raw codestream or JP2 file can be wrapped (re-wrapped in the case
+of JP2) in a user-defined set of JP2 boxes.  To get just a minimal
+JP2 jacket on the codestream provided by `goodstuff.j2k` (a file
+consisting of just a raw codestream), you can use the **wrap** method
+with no box argument: ::
 
     >>> import glymur
     >>> jfile = glymur.data.goodstuff()
@@ -106,10 +107,12 @@ layer (the signature, file type, JP2 header, and contiguous codestream), with
 two additional boxes (image header and color specification) contained in the
 JP2 header superbox.
 
-XML boxes are not in the minimal set of box requirements for the JP2 format, so
-in order to add an XML box into the mix before the codestream box, we'll need to 
-re-specify all of the boxes.  If you already have a JP2 jacket in place, you can just reuse that,
-though.  Take the following example content in an XML file `favorites.xml` : ::
+XML boxes are not in the minimal set of box requirements for the
+JP2 format, so in order to add an XML box into the mix before the
+codestream box, we'll need to re-specify all of the boxes.  If you
+already have a JP2 jacket in place, you can just reuse that, though.
+Take the following example content in an XML file `favorites.xml`
+: ::
 
     <?xml version="1.0"?>
     <favorite_things>
@@ -219,8 +222,8 @@ Here's how the Preview application on the mac shows the RGBA image.
 .. image:: goodstuff_alpha.png
 
     
-work with XMP UUIDs?
-====================
+... work with XMP UUIDs?
+========================
 The example JP2 file shipped with glymur has an XMP UUID. ::
 
     >>> import glymur

docs/source/index.rst

@@ -15,8 +15,10 @@ Contents:
    introduction
    detailed_installation
    how_do_i
-   roadmap
    api
+   roadmap
+   whatsnew/index
+
 
 ------------------
 Indices and tables

docs/source/introduction.rst

@@ -3,7 +3,7 @@ Glymur: a Python interface for JPEG 2000
 ----------------------------------------
 
 **Glymur** is an interface to the OpenJPEG library
-which allows one to read and write JPEG 2000 files from within Python.  
+which allows one to read and write JPEG 2000 files from Python.  
 Glymur supports both reading and writing of JPEG 2000 images, but writing
 JPEG 2000 images is currently limited to images that can fit in memory
 
@@ -18,7 +18,7 @@ Glymur works on Python 2.6, 2.7, 3.3, and 3.4.
 OpenJPEG Installation
 =====================
 Glymur will read JPEG 2000 images with versions 1.3, 1.4, 1.5, 2.0, and 2.1 of
-OpenJPEG.  Writing images is only supported with the 1.5 or better, however,
+OpenJPEG.  Writing images is only supported with OpenJPEG 1.5 or better, however,
 and version 2.1 is strongly recommended.  For more information about OpenJPEG,
 please consult http://www.openjpeg.org.
 

docs/source/whatsnew/0.5.rst

@@ -0,0 +1,50 @@
+=====================
+Changes in glymur 0.5
+=====================
+
+Changes in 0.5.12
+=================
+
+* Minor documentation fixes for grammar and style.
+* The functions removed in 0.5.11 due to API changes in OpenJPEG 2.1.0 were
+  restored for backwards compatibility.  They are deprecated, though, and will
+  be removed in 0.6.0.
+
+    * ``glymur.lib.openjp2.stream_create_default_file_stream_v3``
+    * ``glymur.lib.openjp2.opj.stream_destroy_v3``
+
+
+Changes in 0.5.11
+=================
+
+* Added support for Python 3.4.
+* OpenJPEG 1.5.2 and 2.0.1 are officially supported.
+* OpenJPEG 2.1.0 is officially supported, but the ABI changes introduced by
+  OpenJPEG 2.1.0 required corresponding changes to glymur's ctypes interface.
+  The functions 
+
+    * ``glymur.lib.openjp2.stream_create_default_file_stream_v3``
+    * ``glymur.lib.openjp2.opj.stream_destroy_v3``
+
+  functions were renamed to 
+
+    * ``glymur.lib.openjp2.stream_create_default_file_stream``
+    * ``glymur.lib.openjp2.opj.stream_destroy``
+
+  in order to follow OpenJPEG's upstream changes.  Unless you were using the
+  svn version of OpenJPEG, you should not be affected by this.
+
+
+Changes in 0.5.10
+=================
+
+* Fixed bad warning issued when an unsupported reader requirement box mask
+  length was encountered.
+
+Changes in 0.5.9
+================
+
+* Fixed bad library load on linux as a result of botched 0.5.8 release.
+  This release was primarily aimed at supporting SunPy.
+
+

docs/source/whatsnew/index.rst

@@ -0,0 +1,11 @@
+.. _whatsnew:
+
+**********************
+"What's new" documents
+**********************
+
+These document the changes between minor (or major) versions of glymur.
+
+.. toctree::
+
+    0.5