INITIAL attempt at User Guide in doxygen

doxygen/CMakeLists.txt

@@ -21,7 +21,7 @@ if (DOXYGEN_FOUND)
   set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html)
   set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html)
   set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css)
-  set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileGroup.gif ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileObject.gif ${HDF5_DOXYGEN_DIR}/img/FileFormatSpecChunkDiagram.jpg ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png ${HDF5_DOXYGEN_DIR}/img/IOFlow2.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow3.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow.gif ${HDF5_DOXYGEN_DIR}/img/PaletteExample1.gif ${HDF5_DOXYGEN_DIR}/img/Palettes.fm.anc.gif")
+  set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileGroup.gif ${HDF5_DOXYGEN_DIR}/img/FF-IH_FileObject.gif ${HDF5_DOXYGEN_DIR}/img/FileFormatSpecChunkDiagram.jpg ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png ${HDF5_DOXYGEN_DIR}/img/IOFlow2.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow3.gif ${HDF5_DOXYGEN_DIR}/img/IOFlow.gif ${HDF5_DOXYGEN_DIR}/img/PaletteExample1.gif ${HDF5_DOXYGEN_DIR}/img/Palettes.fm.anc.gif ${HDF5_DOXYGEN_DIR}/img/UML_Attribute.jpg ${HDF5_DOXYGEN_DIR}/img/Shared_Attribute.jpg")
   set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag)
   set (DOXYGEN_SERVER_BASED_SEARCH NO)
   set (DOXYGEN_EXTERNAL_SEARCH NO)

doxygen/Doxyfile.in

@@ -938,7 +938,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = @HDF5_DOXYGEN_DIR@/img
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

doxygen/dox/Overview.dox

@@ -23,7 +23,7 @@ documents cover a mix of tasks, concepts, and reference, to help a specific
 \par Versions
      Version-specific documentation (see the version in the title area) can be found
      here:
-     - HDF5 <code>develop</code> branch (this site)
+     - HDF5 <code>1.10</code> branch (this site)
      - <a href="https://docs.hdfgroup.org/hdf5/v1_12/index.html">HDF5 1.12.x</a>
      - <a href="https://docs.hdfgroup.org/hdf5/v1_10/index.html">HDF5 1.10.x</a>
      - <a href="https://docs.hdfgroup.org/hdf5/v1_8/index.html">HDF5 1.8.x</a>
@@ -36,10 +36,6 @@ documents cover a mix of tasks, concepts, and reference, to help a specific
 \par Offline reading
      You can <a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading.
 
-\par History
-     A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found
-     <a href="https://docs.hdfgroup.org/archive/support/HDF5/doc/index.html">here</a>.
-
 \par ToDo List
      There is plenty of <a href="./todo.html">unfinished business</a>.
 

doxygen/dox/UsersGuide.dox

@@ -0,0 +1,145 @@
+/** \page UG HDF5 User’s Guide
+
+<center>
+HDF5 Release 1.10
+
+\image html HDFG-logo.png "The HDF Group"
+
+</center>
+
+\section sec_data_model The HDF5 Data Model and File Structure
+    - <!-- @ref subsec_data_model_intro --> Introduction
+    - <!-- @ref subsec_data_model_abstract --> The Abstract Data Model
+    - <!-- @ref subsec_data_model_storage --> The HDF5 Storage Model
+    - <!-- @ref subsec_data_model_structure --> The Structure of an HDF5 File
+
+\section sec_program The HDF5 Library and Programming Model
+    - <!-- @ref subsec_program_intro --> Introduction
+    - <!-- @ref subsec_program_model --> The HDF5 Programming Model
+    - <!-- @ref subsec_program_transfer_pipeline --> The Data Transfer Pipeline
+
+\section sec_file The HDF5 File
+    - <!-- @ref subsec_file_intro --> Introduction
+    - <!-- @ref subsec_file_access_modes --> File Access Modes
+    - <!-- @ref subsec_file_creation_access --> File Creation and File Access Properties
+    - <!-- @ref subsec_file_drivers --> Low-level File Drivers
+    - <!-- @ref subsec_file_program_model --> "Programming Model for Files
+    - <!-- @ref subsec_file_h5dump --> Using h5dump to View a File
+    - <!-- @ref subsec_file_summary --> File Function Summaries
+    - <!-- @ref subsec_file_create --> Creating or Opening an HDF5 File
+    - <!-- @ref subsec_file_closes --> Closing an HDF5 File
+    - <!-- @ref subsec_file_property_lists --> File Property Lists
+    - <!-- @ref subsec_file_alternate_drivers --> Alternate File Storage Layouts and Low-level File Drivers
+    - <!-- @ref subsec_file_examples --> Code Examples for Opening and Closing Files
+    - <!-- @ref subsec_file_multiple --> Working with Multiple HDF5 Files
+
+\section sec_group HDF5 Groups
+    - <!-- @ref subsec_group_intro --> Introduction
+    - <!-- @ref subsec_group_descr --> Description of the Group Object
+    - <!-- @ref subsec_group_h5dump --> Using h5dump
+    - <!-- @ref subsec_group_function --> Group Function Summaries
+    - <!-- @ref subsec_group_program --> Programming Model for Groups
+    - <!-- @ref subsec_group_examples --> Examples of File Structures
+
+\section sec_dataset HDF5 Datasets
+    - <!-- @ref subsec_dataset_intro --> Introduction
+    - <!-- @ref subsec_dataset_function --> Dataset Function Summaries
+    - <!-- @ref subsec_dataset_program --> Programming Model for Datasets
+    - <!-- @ref subsec_dataset_transfer --> Data Transfer
+    - <!-- @ref subsec_dataset_allocation --> Allocation of Space in the File
+    - <!-- @ref subsec_dataset_filters --> Using HDF5 Filters
+
+\section sec_datatype HDF5 Datatypes
+
+\section sec_dataspace HDF5 Dataspaces and Partial I/O
+
+\ref sec_attribute
+\li \ref subsec_attribute_intro
+\li \ref subsec_attribute_program
+    <ul>
+        <li> <!-- @ref subsubsec_attribute_program_exist --> To Open and Read or Write an Existing Attribute
+    </ul>
+\li \ref subsec_error_H5A
+\li \ref subsec_attribute_work
+    <ul>
+        <li> \ref subsubsec_attribute_work_struct
+        <li> \ref subsubsec_attribute_work_create
+        <li> \ref subsubsec_attribute_work_access
+        <li> \ref subsubsec_attribute_work_info
+        <li> \ref subsubsec_attribute_work_iterate
+        <li> \ref subsubsec_attribute_work_delete
+        <li> \ref subsubsec_attribute_work_close
+    </ul>
+\li \ref subsec_attribute_special
+
+\ref sec_error
+\li \ref subsec_error_intro
+\li \ref subsec_error_program
+\li \ref subsec_error_H5E
+\li \ref subsec_error_ops
+    <ul>
+        <li> \ref subsubsec_error_ops_stack
+        <li> \ref subsubsec_error_ops_print
+        <li> \ref subsubsec_error_ops_mute
+        <li> \ref subsubsec_error_ops_custom_print
+        <li> \ref subsubsec_error_ops_walk
+        <li> \ref subsubsec_error_ops_travers
+    </ul>
+\li \ref subsec_error_adv
+    <ul>
+        <li> \ref subsubsec_error_adv_more
+        <li> \ref subsubsec_error_adv_app
+    </ul>
+
+\section sec_plist Properties and Property Lists in HDF5
+
+\section sec_addition Additional Resources
+
+<!-- 
+<table>
+<tr><td style="border: none;">
+\li \ref H5A "Attributes (H5A)"
+\li \ref H5D "Datasets (H5D)"
+\li \ref H5S "Dataspaces (H5S)"
+\li \ref H5T "Datatypes (H5T)"
+\li \ref H5E "Error Handling (H5E)"
+\li \ref H5F "Files (H5F)"
+\li \ref H5Z "Filters (H5Z)"
+\li \ref H5G "Groups (H5G)"
+</td><td style="border: none;">
+\li \ref H5I "Identifiers (H5I)"
+\li \ref H5 "Library General (H5)"
+\li \ref H5L "Links (H5L)"
+\li \ref H5O "Objects (H5O)"
+\li \ref H5P "Property Lists (H5P)"
+\li \ref H5PL "Dynamically-loaded Plugins (H5PL)"
+\li \ref H5R "References (H5R)"
+</td><td style="border: none;vertical-align: top;">
+\li \ref api-compat-macros
+\li <a href="./deprecated.html">Deprecated functions</a>
+\li High-level Extensions
+    <ul>
+    <li><a href="https://portal.hdfgroup.org/display/HDF5/Lite">\Bold{HDF5 Lite} (H5LT)</a></li>
+    <li><a href="https://portal.hdfgroup.org/display/HDF5/Images">\Bold{HDF5 Image} (H5IM)</a></li>
+    <li><a href="https://portal.hdfgroup.org/display/HDF5/Tables">\Bold{HDF5 Table} (H5TB)</a></li>
+    <li><a href="https://portal.hdfgroup.org/display/HDF5/Packet+Tables">\Bold{HDF5 Packet Table} (H5TB)</a></li>
+    <li><a href="https://portal.hdfgroup.org/display/HDF5/Dimension+Scales">\Bold{HDF5 Dimension Scale} (H5DS)</a></li>
+    </ul>
+</td></tr>
+<tr><td colspan="3" style="border: none;">
+\ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L
+\ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5Z
+</td></tr>
+</table>
+
+</td></tr>
+</table>
+ -->
+
+\par Don't like what you see? - You can help to improve this User’s Guide
+     Complete the survey linked near the top of this page!\n
+     We treat documentation like code: Fork the
+     <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a
+     <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n
+
+*/

doxygen/hdf5doxy_layout.xml

@@ -5,6 +5,7 @@
     <tab type="user" url="index.html" title="Overview" />
     <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/Learning+HDF5" title="Getting started" />
     <tab type="user" url="@ref Cookbook" title="Cookbook" />
+    <tab type="user" url="@ref UG" title="User Guide" />
     <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides" title="User Guides" />
     <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" />
     <tab type="user" url="@ref GLS" title="Glossary" />