Added what's new pages and minor updates to docstrings for correct AP…

…I-doc gen.

cis/aggregation/aggregation_kernels.py

@@ -10,9 +10,13 @@ def __init__(self):
         super(StddevKernel, self).__init__('standard_deviation', ma.std, ddof=1)
 
     def update_metadata(self, cube, coords, **kwargs):
-        """
+        '''
         Update cube metadata after aggregation
-        """
+        :param cube:
+        :param coords:
+        :param kwargs:
+        :return:
+        '''
         super(StddevKernel, self).update_metadata(cube, coords, **kwargs)
         cube.standard_name = None
         cube.long_name = 'Corrected sample standard deviation of {long_name}'.format(long_name=cube.long_name)

cis/data_io/products/AProduct.py

@@ -37,7 +37,7 @@ def create_data_object(self, filenames, variable):
     @abstractmethod
     def create_coords(self, filenames):
         """
-        Reads the coordinates from a bunch of files
+        Reads the coordinates from multiple files
         :param filenames: List of filenames to read coordinates from
         :return: L{CoordList} object
         """
@@ -47,18 +47,16 @@ def get_file_signature(self):
         """
         :return: a list of regex to match the product's file naming convention.
 
-        Example
-        -------
+        Example::
+            ``return [r'.*CODE*.nc']``
 
-        return [r'.*CODE*.nc']
         This will match all files with a name containing the string 'CODE' and with the 'nc' extension.
 
-        Additional
-        ----------
+        .. note::
 
-        If the signature has matched the framework will call get_file_type_error(filename), this gives the product a
-        chance to open the file and check the contents. If this returns None then the match is complete otherwise
-        the error may be printed for the user
+            If the signature has matched the framework will call get_file_type_error(filename), this gives the product a
+            chance to open the file and check the contents. If this returns None then the match is complete otherwise
+            the error may be printed for the user
         """
 
     def get_variable_names(self, filenames, data_type=None):

cis/data_io/products/gridded_NetCDF.py

@@ -203,7 +203,7 @@ def create_coords(self, filenames, variable=None):
         Note: This calls create_data_object because the coordinates are returned as a Cube.
         :param filenames: list of names of files from which to read coordinates
         :param variable: name of variable for which the coordinates are required
-                         (optional if file contains only one cube)
+        (optional if file contains only one cube)
         :return: iris.cube.Cube
         """
 

cis/plotting/contour_plot.py

@@ -3,12 +3,10 @@
 class Contour_Plot(Generic_Plot):
     #'contour' : PlotType(1, 2, plot_contour),
     def plot(self):
-        '''
+        """
         Plots a contour plot
         Stores the plot in a list to be used for when adding the legend
-
-        :param data_item:    A dictionary containing the x coords, y coords and data as arrays
-        '''
+        """
         self.contour_plot(False)
 
     def set_default_axis_label(self, axis):

doc/collocation.rst

@@ -130,12 +130,12 @@ A full example would be::
 .. _available:
 
 Available Collocators and Kernels
-================================
+=================================
 
-====================== ========================= ================= =================
+====================== ========================= =================== =================
 Collocation type
 ( data -> sample)      Available Collocators      Default Collocator Default Kernel
-====================== ========================= ================= =================
+====================== ========================= =================== =================
 Gridded -> gridded     ``lin``, ``nn``, ``box``  ``lin``           *None*
 Ungridded -> gridded   ``bin``, ``box``          ``bin``           ``moments``
 Gridded -> ungridded   ``nn``, ``lin``           ``nn``            *None*
@@ -144,7 +144,7 @@ Ungridded -> ungridded ``box``                   ``box``           ``moments``
 
 
 Collocation output files
-=======================
+========================
 
 All ungridded collocation output files are prefixed with ``cis-`` and both ungridded and gridded data files are suffixed with ``.nc`` (so there is no need to specify the extension in the output parameter). This is to ensure the cis data product is always used to read collocated ungridded data.
 
@@ -168,7 +168,7 @@ Each collocated output variable has a history attributed created (or appended to
       ...
 
 Basic collocation design
-=======================
+========================
 
 The diagram below demonstrates the basic design of the collocation system, and the roles of each of the components. In the simple case of the default collocator (which returns only one value) the Collocator loops over each of the sample points, calls the relevant constraint to reduce the number of data points, and then the kernel which returns a single value which the collocator stores.
 

doc/collocation_examples.rst

@@ -1,9 +1,9 @@
-===================
+====================
 Collocation Examples
-===================
+====================
 
 Ungridded to Ungridded Collocation Examples
-==========================================
+===========================================
 
 Ungridded data with vertical component
 --------------------------------------
@@ -47,7 +47,7 @@ The files used above can be found at::
 
 
 Ungridded data collocation using k-D tree indexing
--------------------------------------------------
+--------------------------------------------------
 
 These examples show the syntax for using the k-D tree optimisation of the separation constraint. The indexing is only by horizontal position.
 
@@ -282,7 +282,7 @@ The files used above can be found at::
 
 
 Examples of Gridded to Gridded Collocation
-=========================================
+==========================================
 
 Example of Gridded Data onto a Finer Grid
 -----------------------------------------

doc/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to the Community Inter-comparison Suite's documentation!
-====================================================================
+================================================================
 
 Contents:
 
@@ -13,6 +13,7 @@ Contents:
    :numbered:
 
    installation
+   whats_new_1.2
    data_products
    command_line
    file_information

doc/maintenance_and_development.rst

@@ -152,7 +152,7 @@ Here is a sketch of a data product implementation::
 .. _collocation_design:
 
 Collocation
-----------
+-----------
 
 Users can write their own plugins for performing the collocation of two data sets.
 There are three different types of plugin available for collocation and each will be described briefly below.
@@ -224,7 +224,7 @@ sample data points. To enable a constraint to use a AbstractDataOnlyKernel the m
  This may not be called by all collocators who may choose to iterate over all sample points instead. The parameters are
  the same as ``get_iterator``.
 
-Co-locator
+Collocator
 """"""""""
 
 Another plugin which is available is the collocation method itself. A new one can be created by subclassing Collocator and

doc/whats_new_1.1.rst

@@ -0,0 +1,37 @@
+
+=====================
+What's new in CIS 1.1
+=====================
+
+This page documents the new features added, and bugs fixed in CIS since version 1.0. For more detail see all changes here: https://github.com/cedadev/cis/compare/1.0.0...1.1.0
+
+CIS 1.1 features
+================
+
+ * JASMIN-CIS is now called CIS, and the packages, modules and documentation have been renamed accordingly.
+ * Conda packages are now available to allow much easier installation of CIS, and across more platforms: Linux, OSX and Windows.
+ * PyHDF is now an optional dependency. This makes the installation of CIS on e.g. Windows much easier when HDF reading is not required.
+
+Bugs fixed
+==========
+
+ * JASCIS-243 - Error when reading multiple GASSP aircraft files
+ * JASCIS-139 - Updated ungridded aggregation to rename any variables which clash with coordinate variables, as this breaks during the output otherwise.
+ * Compatibility fixes for Numpy versions >1.8 and Python-NetCDF versions >1.1.
+ * Fix Caliop pressure units which were stored as hPA, but need to be hPa to conform to CF.
+ * The integration test data has been moved completely out of the repository - making the download quicker and less bloated. It's location can be specified by setting the CIS_DATA_HOME environment variable.
+ * A test runner has been created to allow easy runnning of the unit and integration test.
+
+
+What's new in CIS 1.1.1
+=======================
+
+This section documents changes in CIS since version 1.1, these were primarily bug fixes and documentation updates. See all changes here: https://github.com/cedadev/cis/compare/1.1.0...1.1.1
+
+Bugs fixed
+==========
+
+ * JASCIS-181 - Updated eval documentation
+ * JASCIS-239 - Documented the requirement of PyHamCrest for running tests
+ * JASCIS-249 - CIS will now accept variables and filenames (such as Windows paths) which include a colon as long as they are escaped with a backslash. E.g. ``cis plot my_var:C\:\my_file.nc``.
+ * Occaisonly HDF will exit when reading an invalid HDF file without throwing any exceptions. To protect against this the HDF reader will now insist on an .hdf extension for any files it reads.

doc/whats_new_1.2.rst

@@ -0,0 +1,26 @@
+
+=====================
+What's new in CIS 1.2
+=====================
+
+This page documents the new features added, and bugs fixed in CIS since version 1.1. See all changes here: https://github.com/cedadev/cis/compare/1.1.0...1.2.0 (or here for now: https://github.com/cedadev/cis/compare/1.1.0...HEAD)
+
+
+CIS 1.2 features
+================
+
+ * All new ``cis info`` command provides much more detailed information about ungridded data variables and enables multiple variables to be output at a time.
+ * Updated a number of routines to take advantage of Iris 1.8 features. In particular gridded-gridded collocation using the nearest neaighbout kernel should be significantly faster. Iris 1.8 is now the minimum version required for CIS.
+ * Gridded-ungridded collocation now supports collocation from cubes with hybrid height coordinates for both nearest neighbour and linear interpolation kernels.
+ * Built-in support for reading multiple HadGEM .pp files directly.
+
+Bugs fixed
+==========
+
+ * JASCIS-253 - Any ungridded points which contain a NaN in any of its coordinate values will now be ignored by CIS
+ * JASCIS-250 - Multiple HadGEM files can now be read correctly through the new data plugins.
+ * JASCIS-197 - Gridded-gridded collocation now respects scalar coordinates
+ * JASCIS-199 - Aggregation now correctly uses the bounds supplied by the user, even when collapsing to length one coordinates.
+ * Speed improvement to the ungridded-gridded collocation using linear interpolation
+ * Several bug fixes for reading multiple GASSP ship files
+ * Renamed and restructured the collocation modules for consistency