Merge pull request #540 from nexusformat/issue_539

Issue 539
nexusformat · Mar 1, 2017 · 2bc51db · 2bc51db
2 parents 1b4457d + 7c21580
commit 2bc51db
Show file tree

Hide file tree

Showing 6 changed files with 113 additions and 49 deletions.
diff --git a/jenkins_build b/jenkins_build
@@ -18,31 +18,34 @@ make
 # publish
 if test "${job_name}" = "master branch"; then
 
+    export WWW_ROOT=/isis/www/nexus
+    mkdir -p ${WWW_ROOT}/doc/examples
+
     # delete after first run
-    rm -fr /isis/www/nexus/doc/nxvalidate
+    rm -fr ${WWW_ROOT}/doc/nxvalidate
 
     cd manual
     cd source
 
-    rm -fr /isis/www/nexus/doc/examples
-    cp -fr examples /isis/www/nexus/doc
+    rm -fr ${WWW_ROOT}/doc/examples
+    cp -fr examples ${WWW_ROOT}/doc
 
     cd ..
     make latexpdf
     cd build
 
     #pdf
-    cp -f latex/nexus.pdf /isis/www/nexus/doc/NeXusManual.pdf
+    cp -f latex/nexus.pdf ${WWW_ROOT}/doc/NeXusManual.pdf
 
     #html
-    rm -fr /isis/www/nexus/doc/html
-    cp -fr html /isis/www/nexus/doc
+    rm -fr ${WWW_ROOT}/doc/html
+    cp -fr html ${WWW_ROOT}/doc
 
     cd ../../..
 
-    ( cd www/download.nexusformat.org; cp -rf * /isis/www/nexus )
+    ( cd www/download.nexusformat.org; cp -rf * ${WWW_ROOT} )
 
-    ( cd impatient-guide && cp -f _build/latex/NXImpatient.pdf /isis/www/nexus/doc/NXImpatient.pdf && rm -rf /isis/www/nexus/doc/impatient && cp -rf _build/html /isis/www/nexus/doc/impatient )
+    ( cd impatient-guide && cp -f _build/latex/NXImpatient.pdf ${WWW_ROOT}/doc/NXImpatient.pdf && rm -rf ${WWW_ROOT}/doc/impatient && cp -rf _build/html ${WWW_ROOT}/doc/impatient )
 fi
 
 exit 0
diff --git a/manual/source/colophon.rst b/manual/source/colophon.rst
@@ -3,7 +3,7 @@ Colophon
 ========
 
 These docs (manual and reference) were produced using :index:`Sphinx <Sphinx (documentation generator)>`
-(http://sphinx.pocoo.org).
+(http://sphinx-doc.org).
 The :index:`source for the manual <manual source>` shows many examples of the structures
 used to create the manual.  If you have any questions about 
 how to contribute to this manual, please contact the NeXus

diff --git a/manual/source/examples/lrmecs/index.rst b/manual/source/examples/lrmecs/index.rst
@@ -1,27 +1,29 @@
 .. _Example-Viewing-LRMECS-Data:
 
-================================================
 Viewing 2-D Data from LRMECS
-================================================
+############################
 
 The IPNS LRMECS instrument stored data in NeXus HDF4 data files.  
 One such example is available from the repository of NeXus data 
-file examples.
+file examples. [#]_
 For this example, we will start with a conversion of that 
 original data file into *HDF5* format.
 
-	:HDF4:
-		http://svn.nexusformat.org/definitions/exampledata/IPNS/LRMECS/lrcs3701.nxs
-	:HDF5:
-		http://svn.nexusformat.org/definitions/exampledata/IPNS/LRMECS/lrcs3701.nx5
+======  =============
+format  file name
+======  =============
+HDF4    lrcs3701.nxs
+HDF5    lrcs3701.nx5
+======  ============= 
 
 This dataset contains two histograms with 2-D images (148x750 and 148x32) of 32-bit integers.
 First, we use the ``h5dump`` tool to investigate the header content of the file 
 (not showing any of the data).
 
+.. [#] LRMECS example data: https://github.com/nexusformat/exampledata/tree/master/IPNS/LRMECS
 
 Visualize Using ``h5dump``
-###############################
+**************************
 
 Here, the output of the command::
 
@@ -30,7 +32,7 @@ Here, the output of the command::
 has been edited to only show the first *NXdata* group (``/Histogram1/data``):
 
 LRMECS ``lrcs3701`` data: ``h5dump`` output
-++++++++++++++++++++++++++++++++++++++++++++++++++
+===========================================
 
 .. literalinclude:: dump-histogram1-data.txt
     :tab-width: 4
@@ -39,7 +41,7 @@ LRMECS ``lrcs3701`` data: ``h5dump`` output
 
 
 Visualize Using *HDFview*
-###############################
+*************************
 
 For many, the simplest way to view the data content 
 of an HDF5 file is to use the  *HDFview* program 
@@ -72,7 +74,7 @@ radio button, and then (accepting everything else as a default) press the
     LRMECS ``lrcs3701`` data: *HDFview* *Open As* dialog
 
 LRMECS ``lrcs3701`` data: image
-++++++++++++++++++++++++++++++++++++++++++++++++++
+===============================
 
 .. figure:: hdfview-image.jpg
     :width: 80%
@@ -81,7 +83,7 @@ LRMECS ``lrcs3701`` data: image
 
 
 Visualize Using *IgorPro*
-###############################
+*************************
 
 Another way to visualize this data is to use a commercial 
 package for scientific data visualization and analysis.  
@@ -132,7 +134,7 @@ to display the image.
     LRMECS ``lrcs3701`` data: *IgorPro* *HDFBrowser* dialog
 
 LRMECS ``lrcs3701`` data: image
-++++++++++++++++++++++++++++++++++++++++++++++++++
+===============================
 
 .. figure:: igor-data.jpg
     :width: 80%

diff --git a/manual/source/history.rst b/manual/source/history.rst
@@ -11,6 +11,12 @@ Two things to note about the development and history of NeXus:
 
 - The NIAC has already discussed many matters related to the format.
 
+.. release_3_2: 
+
+:October 2016:
+    `release 3.2 <https://github.com/nexusformat/definitions/releases/tag/v3.2>`
+    of NeXus Definitions
+
 :2014-12:
     The NIAC approves a new method to identify the default data to be plotted,
     applying attributes at the group level to the root of the HDF5 tree,

diff --git a/manual/source/utilities.rst b/manual/source/utilities.rst
@@ -97,29 +97,6 @@ links to further information, as available.
     All of these concepts are discussed in detail in the documentation
     provided with the source code.
 
-.. index::
-   validation
-   file; validate
-   nxvalidate (utility)
-   cnxvalidate
-   see: cnxvalidate; nxvalidate (utility)
-
-.. _cnxvalidate:
-
-**nxvalidate**
-   The **nxvalidate** code has been re-written entirely in C,
-   to rely on the NXDL class files (base classes and application definitions).
-   The new code is called **cnxvalidate**.
-
-   From the :ref:`nxvalidate` source code documentation: 
-
-      "This is the first version of **nxvalidate** written in C. 
-      Its dependencies are libxml2 and the HDF5 libraries, version 1.8.9 or better. 
-      Its purpose is to validate HDF5 files against NeXus application definitions."
-
-   Note: this tool is lives in its own GitHub repository: [#]_ **cnxvalidate**.
-
-   .. [#] **cnxvalidate**: https://github.com/nexusformat/cnxvalidate
 
 .. index:: 
    plotting
@@ -136,10 +113,56 @@ links to further information, as available.
    single: software
    single: data analysis software
 
+Validation
+##########
+
+The list of applications below are for :ref:`validating <Verification>` NeXus files. 
+The list is not intended to be a complete list of all available packages.
+
+.. index::
+   validation
+   file; validate
+   nxvalidate (utility)
+
+.. _nxvalidate:
+
+**nxvalidate**
+   From the source code documentation: 
+
+   *"This is the first version of nxvalidate written in C. 
+   Its dependencies are libxml2 and the HDF5 libraries, 
+   version 1.8.9 or better. Its purpose is to validate HDF5 
+   data files against NeXus application definitions."*
+
+   Note: this tool is lives in its own GitHub repository **cnxvalidate**:
+   https://github.com/nexusformat/cnxvalidate.git
+
+.. index::
+        validation
+   file; validate
+   punx (utility)
+
+.. _punx:
+
+**punx**
+   Python Utilities for NeXus HDF5 files
+
+   **punx** can validate
+   both NXDL files and NeXus HDF5 data files, as well as print
+   the structure of any HDF5 file, even non-NeXus files.
+
+   NOTE: project is under initial construction, 
+   not yet released for public use, but is useful in its 
+   present form (version 0.0.9).  
+
+   See the program documentation for more details:
+   https://punx.readthedocs.io
++
 Data Analysis
 #############
 
-The list of applications below are some of the utilities that have been developed (or modified) to read/write NeXus files
+The list of applications below are some of the utilities that have been 
+developed (or modified) to read/write NeXus files
 as a data format.  It is not intended to be a complete list of all available packages.
 
 .. index:: 

diff --git a/manual/source/validation.rst b/manual/source/validation.rst
@@ -29,16 +29,46 @@ a laboratory, or even an entire user facility.
 .. index::
    nxvalidate
 
+
+.. TODO
+
+   Chapter should describe how data files are verified (validated) 
+   for conformance to the NeXus standard. 
+   
+   Additional expectation for this chapter 
+   is a description of how validation works.
+
 .. _nxvalidate:
 
 nxvalidate
 ##########
 
-The :ref:`cnxvalidate <cnxvalidate>` utility [#]_, new in 2016, is available for testing. 
-For the moment, the most recent documentation is served from the GitHub web site. 
+The :ref:`cnxvalidate <nxvalidate>` utility [#]_, 
+new in 2016, is available for testing.
+Refer to the GitHub location for the most recent information. 
 
 This utility only works on HDF5 files and is aimed 
 to be faster, simpler, more portable and robust than 
 previous programmes for NeXus file validation.
 
-.. [#] :ref:`cnxvalidate <cnxvalidate>`: from https://github.com/nexusformat/cnxvalidate
+.. [#] :ref:`cnxvalidate <nxvalidate>`: from https://github.com/nexusformat/cnxvalidate
+
+
+
+.. _punx:
+
+punx
+####
+
+Python Utilities for NeXus HDF5 files
+
+**punx** can validate
+both NXDL files and NeXus HDF5 data files, as well as print
+the structure of any HDF5 file, even non-NeXus files.
+
+NOTE: project is under initial construction, 
+not yet released for public use, but is useful in its 
+present form (version 0.0.9).  
+
+See the program documentation for more details:
+https://punx.readthedocs.io