Merge pull request #247 from simphony/feature-adding-cuba-howto

Add basic 'howto' on adding CUBA keywords

doc/source/cuba_information.rst

@@ -1,9 +1,12 @@
+.. _cuba-keywords:
+
 CUBA-Keywords
 =============
 
 
-Common Unified Base Attributes (CUBA) are a list of common keywords transcending across different scales, methods and modelling-engines.  They provide a standard nomenclature for attributes (variables and parameters) in SimPhoNy.
+Common Unified Basic Attributes (CUBA) are a list of common keywords transcending across different scales, methods and modelling-engines.  They provide a standard nomenclature for attributes (variables and parameters) in SimPhoNy.
 
 More detailed information for each CUBA-keyword is provided in the following table.
 
+
 .. include:: cuba.rst 

doc/source/plugins.rst → doc/source/extending_simphony.rst

@@ -1,5 +1,8 @@
+Extending SimPhoNy
+==================
+
 Plugins
-=======
+-------
 
 The SimPhoNy library can extended through two `entry points`_ for
 contributing python modules that contain engine and visualisation components:
@@ -51,3 +54,32 @@ Will allow the user to import the new engine from inside the ``simphony`` module
 
 
 .. _entry points : http://pythonhosted.org/setuptools/pkg_resources.html#entry-points
+
+
+CUBA keywords
+-------------
+
+Common Unified Basic Attributes (CUBA) are a list of common keywords transcending
+across different scales, methods and modelling-engines. As SimPhoNy is extended,
+there is a need for CUBA to also be extended. Before adding a CUBA, developers
+should first consult the list of existing :ref:`cuba-keywords`,
+to see if the keyword already exists. Contact the developers at
+https://github.com/simphony/simphony-common if there are any questions.
+
+Once you have decided upon what CUBA needs to be added (or modified), edit
+`simphony/core/cuba.yml` to add the respective keyword. Ensure that all the
+the required information is accurately provided.
+
+Developers should then use cuba_generate.py to generate four files which are
+based on the contents of cuba.yml::
+
+   python simphony/scripts/cuba_generate.py python simphony/core/cuba.yml simphony/core/cuba.py
+   python simphony/scripts/cuba_generate.py keywords simphony/core/cuba.yml simphony/core/keywords.py
+   python simphony/scripts/cuba_generate.py rst simphony/core/cuba.yml doc/source/cuba.rst
+   python simphony/scripts/cuba_generate.py table simphony/core/cuba.yml simphony/io/data_container_description.py
+
+Finally, a pull request should be created and reviewed.
+
+Also note that the H5_FILE_VERSION version of :class:`~.H5CUDS` will usually
+have to be updated for each release of SimPhoNy when the list of CUBA keywords
+has been modified.

doc/source/index.rst

@@ -14,7 +14,7 @@ User Manual
 .. toctree::
    :maxdepth: 1
 
-   Extending Simphony <plugins>
+   Extending SimPhoNy <extending_simphony>
    CUBA <cuba_information>
    CUDS <cuds_definition>
    HDF5 Storage <hdf5_storage>