diff --git a/docs/bnf/attribute_collection.rst b/docs/bnf/attribute_collection.md similarity index 62% rename from docs/bnf/attribute_collection.rst rename to docs/bnf/attribute_collection.md index ffe6e2c..9ea5978 100644 --- a/docs/bnf/attribute_collection.rst +++ b/docs/bnf/attribute_collection.md @@ -1,16 +1,17 @@ -Attribute -========= +# Attribute +```{eval-rst} .. productionlist:: attribute_collection: "[" `attribute_list` "]" attribute_list: `attribute` ("," `attribute`)* attribute: "{" : "name" ":" `ascii_string` | `unicode_string` "," - : "type" ":" `datatype` | `datatype_ref` "," - : "shape" ":" `dataspace` "," - : "value" ":" `json_value` "," + : "type" ":" `datatype` | `datatype_ref` "," + : "shape" ":" `dataspace` "," + : "value" ":" `json_value` "," : "creationProperties" ":" `acpl` - : "}" + : "}" acpl: "{" : "nameCharEncoding" ":" `char_encoding` : "}" +``` diff --git a/docs/bnf/dataset.rst b/docs/bnf/dataset.md similarity index 69% rename from docs/bnf/dataset.rst rename to docs/bnf/dataset.md index 6ac829a..d64f49b 100644 --- a/docs/bnf/dataset.rst +++ b/docs/bnf/dataset.md @@ -1,20 +1,22 @@ -Dataset -======= +# Dataset +```{eval-rst} .. productionlist:: dataset: `identifier` ":" "{" : "alias" ":" `hdf5_path_name_array` - : "attributes" ":" `attribute_collection` "," - : "type" ":" `datatype` | `datatype_ref` "," - : "shape" ":" `dataspace` "," - : "value" ":" `json_value` "," - : "creationProperties" ":" `dcpl` - : "}" + : "attributes" ":" `attribute_collection` "," + : "type" ":" `datatype` | `datatype_ref` "," + : "shape" ":" `dataspace` "," + : "value" ":" `json_value` "," + : "creationProperties" ":" `dcpl` + : "}" json_value: `json_string` :| `json_number` :| `json_array` :| `json_null` +``` +```{eval-rst} .. productionlist:: dcpl: "{" : "allocTime" ":" `alloc_time` "," @@ -28,11 +30,11 @@ Dataset : "}" alloc_time: "H5D_ALLOC_TIME_DEFAULT" :| "H5D_ALLOC_TIME_EARLY" - :| "H5D_ALLOC_TIME_INCR" - :| "H5D_ALLOC_TIME_LATE" + :| "H5D_ALLOC_TIME_INCR" + :| "H5D_ALLOC_TIME_LATE" fill_time: "H5D_FILL_TIME_IFSET" :| "H5D_FILL_TIME_ALLOC" - :| "H5D_FILL_TIME_NEVER" + :| "H5D_FILL_TIME_NEVER" fill_value: `json_value` layout: `chunked_layout` | `compact_layout` | `contiguous_layout` chunked_layout: "{" @@ -44,12 +46,13 @@ Dataset : "}" contiguous_layout: "{" : "class" ":" "H5D_CONTIGUOUS" "," - : "externalStorage" ":" `external` + : "externalStorage" ":" `external` : "}" external: "[" `file_extent_list` "]" file_extent_list: `file_extent` ("," `file_extent`)* file_extent: "{" : "name" ":" `ascii_string` "," - : "offset" ":" `non_negative_integer` - : "size" ":" `positive_integer` - : "}" + : "offset" ":" `non_negative_integer` + : "size" ":" `positive_integer` + : "}" +``` diff --git a/docs/bnf/dataspace.rst b/docs/bnf/dataspace.md similarity index 64% rename from docs/bnf/dataspace.rst rename to docs/bnf/dataspace.md index 9a4e695..cfb17d3 100644 --- a/docs/bnf/dataspace.rst +++ b/docs/bnf/dataspace.md @@ -1,34 +1,37 @@ -Dataspace -========= +# Dataspace +```{eval-rst} .. productionlist:: dataspace: `null_dataspace` | `scalar_dataspace` | `simple_dataspace` null_dataspace: "{" - : "class" ":" "H5S_NULL" - : "}" + : "class" ":" "H5S_NULL" + : "}" scalar_dataspace: "{" - : "class" ":" "H5S_SCALAR" - : "}" + : "class" ":" "H5S_SCALAR" + : "}" simple_dataspace: "{" - : "class" ":" "H5S_SIMPLE" "," + : "class" ":" "H5S_SIMPLE" "," : "dims" ":" `dims_array` "," : "maxdims" ":" `maxdims_array` - : "}" + : "}" +``` +```{eval-rst} .. productionlist:: dataspace_selection: "{" : "class" ":" `selection_class` "," - : "selection" ":" ( `hyperslab_selection` - : | `point_selection`) + : "selection" ":" ( `hyperslab_selection` + : | `point_selection`) selection_class: "H5S_SEL_HYPERSLABS" :| "H5S_SEL_POINTS" hyperslab_selection: "[" `block_list` "]" block_list: `block` ("," `block`)* block: "{" : "start" ":" `coordinate` "," - : "opposite" ":" `coordinate` - : "}" + : "opposite" ":" `coordinate` + : "}" point_selection: "[" `coordinate_list` "]" coordinate_list: `coordinate` ("," `coordinate`)* coordinate: `non_negative_integer_array` +``` diff --git a/docs/bnf/datatype.rst b/docs/bnf/datatype.md similarity index 57% rename from docs/bnf/datatype.rst rename to docs/bnf/datatype.md index 400607f..669e924 100644 --- a/docs/bnf/datatype.rst +++ b/docs/bnf/datatype.md @@ -1,6 +1,6 @@ -Datatype -======== +# Datatype +```{eval-rst} .. productionlist:: datatype_object: `identifier` ":" "{" : "alias" ":" `hdf5_path_name_array` @@ -17,15 +17,19 @@ Datatype :| `string_datatype` :| `vlen_datatype` +``` +```{eval-rst} .. productionlist:: array_datatype: "{" : "class" ":" "H5T_ARRAY" "," : "base" ":" `datatype` | `datatype_ref` "," - : "dims" ":" `dims_array` - : "}" + : "dims" ":" `dims_array` + : "}" +``` +```{eval-rst} .. productionlist:: bitfield_datatype: "{" : "class" ":" "H5T_BITFIELD" "," @@ -34,46 +38,52 @@ Datatype bitfield_predef: "base" ":" : ( "H5T_STD_B8BE" | "H5T_STD_B8LE" :| "H5T_STD_B16BE" | "H5T_STD_B16LE" - :| "H5T_STD_B32BE" | "H5T_STD_B32LE" - :| "H5T_STD_B64BE" | "H5T_STD_B64LE" ) + :| "H5T_STD_B32BE" | "H5T_STD_B32LE" + :| "H5T_STD_B64BE" | "H5T_STD_B64LE" ) bitfield_user : "bitOffset" ":" `non_negative_integer` "," - : "byteOrder" ":" `byte_order` "," - : "lsbPad" ":" `bit_padding` "," - : "msbPad" ":" `bit_padding` "," - : "precision" ":" `positive_integer` "," - : "size" ":" `positive_integer` + : "byteOrder" ":" `byte_order` "," + : "lsbPad" ":" `bit_padding` "," + : "msbPad" ":" `bit_padding` "," + : "precision" ":" `positive_integer` "," + : "size" ":" `positive_integer` bit_padding : "H5T_PAD_ZERO" :| "H5T_PAD_ONE" - :| "H5T_PAD_BACKGROUND" + :| "H5T_PAD_BACKGROUND" byte_order : "H5T_ORDER_LE" | "H5T_ORDER_BE" +``` +```{eval-rst} .. productionlist:: compound_datatype: "{" : "class" ":" "H5T_COMPOUND" "," - : "fields" ":" "[" `field_list` "]" - : "}" + : "fields" ":" "[" `field_list` "]" + : "}" field_list: `field_def` ("," `field_def`)* field_def: "{" : "name" ":" `ascii_string` "," - : "type" ":" `datatype` | `datatype_ref` "," - : "}" + : "type" ":" `datatype` | `datatype_ref` "," + : "}" +``` +```{eval-rst} .. productionlist:: enumeration_datatype: "{" - : "base" ":" ( `integer_datatype` | + : "base" ":" ( `integer_datatype` | : `datatype_reference` ) "," : "class" ":" "H5T_ENUM" "," - : "members" ":" "[" `enum_member_list` "]" - : "}" + : "members" ":" "[" `enum_member_list` "]" + : "}" enum_member_list: `enum_member` ("," `enum_member`)* enum_member: "{" : "name" ":" `ascii_string` "," : "value" ":" `integer` : "}" +``` +```{eval-rst} .. productionlist:: floating_point_datatype: "{" : "class" ":" "H5T_FLOAT" "," @@ -84,24 +94,26 @@ Datatype :| "H5T_IEEE_F64BE" | "H5T_IEEE_F64LE" ) float_user: "{" : "bitOffset" ":" `non_negative_integer` "," - : "byteOrder" ":" `byte_order` "," - : "expBias" ":" `positive_integer` "," - : "expBits" ":" `positive_integer` "," - : "expBitPos" ":" `positive_integer` "," - : "intlbPad" ":" `bit_padding` "," - : "lsbPad" ":" `bit_padding` "," - : "mantBits" ":" `positive_integer` "," - : "mantBitPos" ":" `non_negative_integer` "," - : "mantNorm" ":" `mant_norm` "," - : "msbitPad" ":" `bit_padding` "," - : "precision" ":" `positive_integer` "," - : "signBitPos" ":" `positive_integer` "," - : "size" ":" `positive_integer` - : "}" + : "byteOrder" ":" `byte_order` "," + : "expBias" ":" `positive_integer` "," + : "expBits" ":" `positive_integer` "," + : "expBitPos" ":" `positive_integer` "," + : "intlbPad" ":" `bit_padding` "," + : "lsbPad" ":" `bit_padding` "," + : "mantBits" ":" `positive_integer` "," + : "mantBitPos" ":" `non_negative_integer` "," + : "mantNorm" ":" `mant_norm` "," + : "msbitPad" ":" `bit_padding` "," + : "precision" ":" `positive_integer` "," + : "signBitPos" ":" `positive_integer` "," + : "size" ":" `positive_integer` + : "}" mant_norm: "H5T_NORM_IMPLIED" :| "H5T_NORM_MSBSET" - :| "H5T_NORM_NONE" + :| "H5T_NORM_NONE" +``` +```{eval-rst} .. productionlist:: integer_datatype: "{" : "class" ":" "H5T_INTEGER" "," @@ -110,31 +122,35 @@ Datatype integer_predef: "base" ":" : ( "H5T_STD_I8BE" | "H5T_STD_I8LE" :| "H5T_STD_I16BE" | "H5T_STD_I16LE" - :| "H5T_STD_I32BE" | "H5T_STD_I32LE" - :| "H5T_STD_I64BE" | "H5T_STD_I64LE" - :| "H5T_STD_U8BE" | "H5T_STD_U8LE" - :| "H5T_STD_U16BE" | "H5T_STD_U16LE" - :| "H5T_STD_U32BE" | "H5T_STD_U32LE" - :| "H5T_STD_U64BE" | "H5T_STD_U64LE" ) + :| "H5T_STD_I32BE" | "H5T_STD_I32LE" + :| "H5T_STD_I64BE" | "H5T_STD_I64LE" + :| "H5T_STD_U8BE" | "H5T_STD_U8LE" + :| "H5T_STD_U16BE" | "H5T_STD_U16LE" + :| "H5T_STD_U32BE" | "H5T_STD_U32LE" + :| "H5T_STD_U64BE" | "H5T_STD_U64LE" ) integer_user: "{" - : "bitOffset" ":" `non_negative_integer` "," - : "byteOrder" ":" `byte_order` "," - : "lsbPad" ":" `bit_padding` "," - : "msbPad" ":" `bit_padding` "," - : "precision" ":" `positive_integer` "," - : "signType" ":" `sign_type` "," - : "size" ":" `positive_integer` - : "}" + : "bitOffset" ":" `non_negative_integer` "," + : "byteOrder" ":" `byte_order` "," + : "lsbPad" ":" `bit_padding` "," + : "msbPad" ":" `bit_padding` "," + : "precision" ":" `positive_integer` "," + : "signType" ":" `sign_type` "," + : "size" ":" `positive_integer` + : "}" sign_type: "H5T_SGN_NONE" | "H5T_SGN_2" +``` +```{eval-rst} .. productionlist:: opaque_datatype: "{" : "class" ":" "H5T_OPAQUE" "," : "size" ":" `positive_integer` "," - : "tag" ":" `ascii_string` + : "tag" ":" `ascii_string` : "}" +``` +```{eval-rst} .. productionlist:: reference_datatype: "{" : "class" ":" "H5T_REFERENCE" "," @@ -144,28 +160,33 @@ Datatype object_reference_value: `path` region_reference_value: "{" : "dataset" ":" `dataset_ref` ";" - : "selection" ":" `dataspace_selection` + : "selection" ":" `dataspace_selection` : "}" dataset_ref: "datasets/" `id_reference` datatype_ref: "datatypes/" `id_reference` group_ref: "groups/" `id_reference` +``` +```{eval-rst} .. productionlist:: string_datatype: "{" : "charSet" ":" `char_encoding` : "class" ":" "H5T_STRING" "," - : "length" " ":" `string_length` - : "strPad" ":" `string_padding` "," + : "length" " ":" `string_length` + : "strPad" ":" `string_padding` "," : "}" char_encoding: "H5T_CSET_ASCII" | "H5T_CSET_UTF8" string_length: `positive_integer` | "H5T_VARIABLE" string_padding: "H5T_STR_NULLTERM" :| "H5T_STR_NULLPAD" - :| "H5T_STR_SPACEPAD" + :| "H5T_STR_SPACEPAD" +``` +```{eval-rst} .. productionlist:: vlen_datatype: "{" : "class" ":" "H5T_VLEN" "," - : "base" ":" `datatype` | `datatype_ref` "," - : "}" + : "base" ":" `datatype` | `datatype_ref` "," + : "}" +``` diff --git a/docs/bnf/file.rst b/docs/bnf/file.md similarity index 73% rename from docs/bnf/file.rst rename to docs/bnf/file.md index 87570c8..e3bc165 100644 --- a/docs/bnf/file.rst +++ b/docs/bnf/file.md @@ -1,6 +1,6 @@ -File -==== +# File +```{eval-rst} .. productionlist:: file: "{" : "id" ":" `identifier` "," @@ -16,12 +16,16 @@ File : "driverInfo" ":" `file_driver_info` "," : "apiVersion" ":" "1.0.0" : "}" +``` +```{eval-rst} .. productionlist:: group_hashtable: `group` ("," `group`)* dataset_hashtable: `dataset` ("," `dataset`)* datatype_hashtable: `datatype_object` ("," `datatype_object`)* +``` +```{eval-rst} .. productionlist:: fcpl: "{" : "chunkStorageConfig" ":" `chunk_storage_config` "," @@ -31,50 +35,62 @@ File : "superBlockVersion" ":" `non_negative_integer` "," : "symbolTableConfig" ":" `sym_tab_config` "," : "}" +``` +```{eval-rst} .. productionlist:: chunk_storage_config: "{" : "chunkStorageBTreeHalfRank" ":" `positive_integer` - : "}" + : "}" +``` +```{eval-rst} .. productionlist:: free_list_config: "{" : "freeListVersion" ":" `non_negative_integer` - : "}" + : "}" - +``` + +```{eval-rst} .. productionlist:: size_config: "{" : "lengthSizeInBytes" ":" `positive_integer` - : "offsetSizeInBytes" ":" `positive_integer` - : "}" + : "offsetSizeInBytes" ":" `positive_integer` + : "}" +``` +```{eval-rst} .. productionlist:: sohm_config: "{" : "maxList" ":" `non_negative_integer` "," : "minBTree" ":" `non_negative_integer` "," : "version" ":" `non_negative_integer` "," - : "indexes" ":" "[" `sohm_index_list` "]" + : "indexes" ":" "[" `sohm_index_list` "]" : "}" sohm_index_list: `sohm_index` ("," `sohm_index`)* sohm_index: "{" : "messageTypes" ":" "[" `sohm_message_type_list` "]" "," - : "minMessageSize" ":" `non_negative_integer` + : "minMessageSize" ":" `non_negative_integer` : "}" sohm_message_type_list: `sohm_message_type` ("," `sohm_message_type`)* sohm_message_type: "H5O_SHMESG_ATTR_FLAG" :| "H5O_SHMESG_DTYPE_FLAG" - :| "H5O_SHMESG_FILL_FLAG" - :| "H5O_SHMESG_PLINE_FLAG" - :| "H5O_SHMESG_SDSPACE_FLAG" - + :| "H5O_SHMESG_FILL_FLAG" + :| "H5O_SHMESG_PLINE_FLAG" + :| "H5O_SHMESG_SDSPACE_FLAG" +``` + +```{eval-rst} .. productionlist:: sym_tab_config: "{" : "nodeSize" ":" `positive_integer` - : "treeRank" ":" `positive_integer` - : "version" ":" `non_negative_integer` - : "}" + : "treeRank" ":" `positive_integer` + : "version" ":" `non_negative_integer` + : "}" +``` +```{eval-rst} .. productionlist:: file_driver_info: `family_driver_info` | `multi_driver_info` family_driver_info: "{" @@ -84,13 +100,14 @@ File data_distribution_list: `data_item` ("," `data_item`)* data_item: "{" : "dataMap" ":" `data_kind` "," - : "fileName" ":" `unicode_string` "," - : "address" ":" `positive_integer` "," - : "relaxFlag" ":" false | true + : "fileName" ":" `unicode_string` "," + : "address" ":" `positive_integer` "," + : "relaxFlag" ":" false | true : "}" data_kind: "H5FD_MEM_SUPER" :| "H5FD_MEM_BTREE" - :| "H5FD_MEM_DRAW" - :| "H5FD_MEM_GHEAP" - :| "H5FD_MEM_LHEAP" - :| "H5FD_MEM_OHDR" + :| "H5FD_MEM_DRAW" + :| "H5FD_MEM_GHEAP" + :| "H5FD_MEM_LHEAP" + :| "H5FD_MEM_OHDR" +``` diff --git a/docs/bnf/filters.md b/docs/bnf/filters.md new file mode 100644 index 0000000..f439e83 --- /dev/null +++ b/docs/bnf/filters.md @@ -0,0 +1,91 @@ +# Filter + +```{eval-rst} +.. productionlist:: + filter_list: `filter` ("," `filter`)* + filter: `deflate_filter` + :| `fletcher32_filter` + :| `lzf_filter` + :| `nbit_filter` + :| `scaleoffset_filter` + :| `shuffle_filter` + :| `szip_filter` + :| `other_filter` +``` + +```{eval-rst} +.. productionlist:: + deflate_filter: "{" + : "class" ":" "H5Z_FILTER_DEFLATE" "," + : "id" ":" 1 "," + : "level" ":" /[0-9]/ + : "}" +``` + +```{eval-rst} +.. productionlist:: + fletcher32_filter: "{" + : "class" ":" "H5Z_FILTER_FLETCHER32" "," + : "id" ":" 3 + : "}" +``` + +```{eval-rst} +.. productionlist:: + lzf_filter: "{" + : "class" ":" "H5Z_FILTER_LZF" "," + : "id" ":" 32000 + : "}" +``` + +```{eval-rst} +.. productionlist:: + nbit_filter: "{" + : "class" ":" "H5Z_FILTER_NBIT" "," + : "id" ":" 5 + : "}" +``` + +```{eval-rst} +.. productionlist:: + scaleoffset_filter: "{" + : "class" ":" "H5Z_FILTER_SCALEOFFSET" "," + : "id" ":" 6 "," + : "scaleType" ":" `scale_type` "," + : "scaleOffset" ":" `positive_integer` + : "}" + scale_type: "H5Z_SO_FLOAT_DSCALE" + :| "H5Z_SO_FLOAT_ESCALE" + :| "H5Z_SO_INT" +``` + +```{eval-rst} +.. productionlist:: + shuffle_filter: "{" + : "class" ":" "H5Z_FILTER_SHUFFLE" "," + : "id" ":" 2 + : "}" +``` + +```{eval-rst} +.. productionlist:: + szip_filter: "{" + : "class" ":" "H5Z_FILTER_SZIP" "," + : "id" ":" 4 "," + : "bitsPerPixel" ":" `positive_integer` "," + : "coding" ":" `coding` "," + : "pixelsPerBlock" ":" `positive_integer` "," + : "pixelsPerScanline" ":" `positive_integer` + : "}" + coding: "H5_SZIP_EC_OPTION_MASK" + :| "H5_SZIP_NN_OPTION_MASK" +``` + +```{eval-rst} +.. productionlist:: + other_filter: "{" + : "class" ":" "H5Z_FILTER_USER" "," + : "id" ":" `positive_integer` "," + : "parameters" ":" `positive_integer_array` + : "}" +``` diff --git a/docs/bnf/filters.rst b/docs/bnf/filters.rst deleted file mode 100644 index c68d7ac..0000000 --- a/docs/bnf/filters.rst +++ /dev/null @@ -1,74 +0,0 @@ -Filter -====== - -.. productionlist:: - filter_list: `filter` ("," `filter`)* - filter: `deflate_filter` - :| `fletcher32_filter` - :| `lzf_filter` - :| `nbit_filter` - :| `scaleoffset_filter` - :| `shuffle_filter` - :| `szip_filter` - :| `other_filter` - -.. productionlist:: - deflate_filter: "{" - : "class" ":" "H5Z_FILTER_DEFLATE" "," - : "id" ":" 1 "," - : "level" ":" /[0-9]/ - : "}" - -.. productionlist:: - fletcher32_filter: "{" - : "class" ":" "H5Z_FILTER_FLETCHER32" "," - : "id" ":" 3 - : "}" - -.. productionlist:: - lzf_filter: "{" - : "class" ":" "H5Z_FILTER_LZF" "," - : "id" ":" 32000 - : "}" - -.. productionlist:: - nbit_filter: "{" - : "class" ":" "H5Z_FILTER_NBIT" "," - : "id" ":" 5 - : "}" - -.. productionlist:: - scaleoffset_filter: "{" - : "class" ":" "H5Z_FILTER_SCALEOFFSET" "," - : "id" ":" 6 "," - : "scaleType" ":" `scale_type` "," - : "scaleOffset" ":" `positive_integer` - : "}" - scale_type: "H5Z_SO_FLOAT_DSCALE" - :| "H5Z_SO_FLOAT_ESCALE" - :| "H5Z_SO_INT" - -.. productionlist:: - shuffle_filter: "{" - : "class" ":" "H5Z_FILTER_SHUFFLE" "," - : "id" ":" 2 - : "}" - -.. productionlist:: - szip_filter: "{" - : "class" ":" "H5Z_FILTER_SZIP" "," - : "id" ":" 4 "," - : "bitsPerPixel" ":" `positive_integer` "," - : "coding" ":" `coding` "," - : "pixelsPerBlock" ":" `positive_integer` "," - : "pixelsPerScanline" ":" `positive_integer` - : "}" - coding: "H5_SZIP_EC_OPTION_MASK" - :| "H5_SZIP_NN_OPTION_MASK" - -.. productionlist:: - other_filter: "{" - : "class" ":" "H5Z_FILTER_USER" "," - : "id" ":" `positive_integer` "," - : "parameters" ":" `positive_integer_array` - : "}" diff --git a/docs/bnf/group.rst b/docs/bnf/group.md similarity index 80% rename from docs/bnf/group.rst rename to docs/bnf/group.md index ea4aba4..2cb529f 100644 --- a/docs/bnf/group.rst +++ b/docs/bnf/group.md @@ -1,16 +1,18 @@ -Group -===== +# Group +```{eval-rst} .. productionlist:: group: `identifier` ":" "{" : "alias" ":" `hdf5_path_name_array` - : "attributes" ":" `attribute_collection` "," - : "links" ":" `link_collection` "," - : "created" ":" `utc_datetime` "," - : "lastModified" ":" `utc_datetime` "," - : "creationProperties" ":" `gcpl` + : "attributes" ":" `attribute_collection` "," + : "links" ":" `link_collection` "," + : "created" ":" `utc_datetime` "," + : "lastModified" ":" `utc_datetime` "," + : "creationProperties" ":" `gcpl` : "}" +``` +```{eval-rst} .. productionlist:: link_collection: "[" `link_list` "]" link_list: `link` ("," `link`)* @@ -45,7 +47,9 @@ Group : "charSet" ":" `char_encoding` : "creationOrder" ":" `non_negative_integer` : "}" +``` +```{eval-rst} .. productionlist:: gcpl: "{" : `ocp` "," @@ -60,10 +64,11 @@ Group :| "H5P_CRT_ORDER_INDEXED" link_phase_change: "{" : "maxCompact" ":" `non_negative_integer` "," - : "minDense" ":" `non_negative_integer` - : "}" + : "minDense" ":" `non_negative_integer` + : "}" links_estimate: "{" : "numEntries" ":" `non_negative_integer` "," - : "nameLength" ":" `non_negative_integer` - : "}" + : "nameLength" ":" `non_negative_integer` + : "}" link_name_filter_list: `deflate_filter` +``` diff --git a/docs/bnf/index.md b/docs/bnf/index.md new file mode 100644 index 0000000..5a2e653 --- /dev/null +++ b/docs/bnf/index.md @@ -0,0 +1,14 @@ +# Backus-Naur Grammar + +HDF5/JSON specification in the Backus-Naur form. + +```{toctree} +file +group +dataset +dataspace +datatype +attribute_collection +filters +misc +``` diff --git a/docs/bnf/index.rst b/docs/bnf/index.rst deleted file mode 100644 index 0b5475e..0000000 --- a/docs/bnf/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -Backus-Naur Grammar -=================== - -HDF5/JSON specification in the Backus-Naur form. - -.. toctree:: - - file.rst - group.rst - dataset.rst - dataspace.rst - datatype.rst - attribute_collection.rst - filters.rst - misc.rst diff --git a/docs/bnf/misc.rst b/docs/bnf/misc.md similarity index 84% rename from docs/bnf/misc.rst rename to docs/bnf/misc.md index e9ad6ac..db33fc5 100644 --- a/docs/bnf/misc.rst +++ b/docs/bnf/misc.md @@ -1,6 +1,6 @@ -Miscellaneous -============= +# Miscellaneous +```{eval-rst} .. productionlist:: ocp: "attributeCreationOrder" ":" `attr_crt_order` "," : "attributePhaseChange" ":" `attr_phase_change` "," @@ -9,12 +9,15 @@ Miscellaneous :| "H5P_CRT_ORDER_INDEXED" attr_phase_change: "{" : "maxCompact" ":" `non_negative_integer` "," - : "minDense" ":" `non_negative_integer` - : "}" + : "minDense" ":" `non_negative_integer` + : "}" track_times: "false" | "true" +``` -.. rubric:: URL +```{rubric} URL +``` +```{eval-rst} .. productionlist:: url: `scheme` "://" `domain` [ ":" `port` ] "/" `path` [ "#" `fragment` ] scheme: "file" | "http" @@ -22,16 +25,21 @@ Miscellaneous port: `non_negative_integer` path: ( "datasets" | "datatypes" | "groups" ) "/" `identifier` fragment: "h5(" `hdf5_path_name` ")" +``` +```{eval-rst} .. productionlist:: hdf5_path_name_array: "[" `hdf5_path_name_list` "]" hdf5_path_name_list: `hdf5_path_name`, ("," `hdf5_path_name`)* hdf5_path_name: [ "/" ] `link_name` ("/" `link_name` )* link_name: ascii_string_wo_slash | unicode_string_wo_slash +``` -.. rubric:: Simple Types +```{rubric} Simple Types +``` +```{eval-rst} .. productionlist:: byte_array: "[" `byte_list` "]" byte_list: `byte_value` ("," `byte_value`)* @@ -48,23 +56,33 @@ Miscellaneous positive_integer_list: `positive_integer` : ("," `positive_integer`)* positive_integer: /integer > 0/ +``` -.. rubric:: Date and Time +```{rubric} Date and Time +``` +```{eval-rst} .. productionlist:: utc_datetime: **TBD** +``` -.. rubric:: Strings +```{rubric} Strings +``` +```{eval-rst} .. productionlist:: ascii_string_wo_slash: **TBD** ascii_string: **TBD** unicode_string_wo_slash: **TBD** unicode_string: **TBD** +``` -.. rubric:: Identifier +```{rubric} Identifier +``` +```{eval-rst} .. productionlist:: id_reference: `identifier` identifier: `uuid` | **TBD** uuid: /[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/ +``` diff --git a/docs/conf.py b/docs/conf.py index a328172..82a9815 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,13 +9,22 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.autodoc", "sphinx.ext.todo"] +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.todo", + "sphinx_copybutton", + "myst_parser" +] + +myst_enable_extensions = [ + "deflist" +] # Add any paths that contain templates here, relative to this directory. # templates_path = ["_templates"] # The suffix of source filenames. -source_suffix = ".rst" +source_suffix = ".md" # The encoding of source files. # source_encoding = 'utf-8-sig' diff --git a/docs/examples/array_dset.md b/docs/examples/array_dset.md new file mode 100644 index 0000000..672fc36 --- /dev/null +++ b/docs/examples/array_dset.md @@ -0,0 +1,5 @@ +# An HDF5 Array Datatype + +```{literalinclude} array_dset.json +:language: json +``` diff --git a/docs/examples/array_dset.rst b/docs/examples/array_dset.rst deleted file mode 100644 index 683ff8d..0000000 --- a/docs/examples/array_dset.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Array Datatype -====================== - -.. literalinclude:: array_dset.json - :language: json diff --git a/docs/examples/classic.md b/docs/examples/classic.md new file mode 100644 index 0000000..75e951b --- /dev/null +++ b/docs/examples/classic.md @@ -0,0 +1,8 @@ +# The "Classic" + +This example is equivalent to the one in Section 4 of +[DDL in BNF for HDF5](https://portal.hdfgroup.org/display/HDF5/DDL+in+BNF+for+HDF5-1.12+and+above). + +```{literalinclude} classic.json +:language: json +``` diff --git a/docs/examples/classic.rst b/docs/examples/classic.rst deleted file mode 100644 index c6a16de..0000000 --- a/docs/examples/classic.rst +++ /dev/null @@ -1,8 +0,0 @@ -The "Classic" -============= - -This example is equivalent to the one in Section 4 of -`DDL in BNF for HDF5 `_. - -.. literalinclude:: classic.json - :language: json diff --git a/docs/examples/compound.md b/docs/examples/compound.md new file mode 100644 index 0000000..93b3f98 --- /dev/null +++ b/docs/examples/compound.md @@ -0,0 +1,5 @@ +# An HDF5 Compound Datatype + +```{literalinclude} compound.json +:language: json +``` diff --git a/docs/examples/compound.rst b/docs/examples/compound.rst deleted file mode 100644 index ee4b9c3..0000000 --- a/docs/examples/compound.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Compound Datatype -========================= - -.. literalinclude:: compound.json - :language: json diff --git a/docs/examples/datatype_object.md b/docs/examples/datatype_object.md new file mode 100644 index 0000000..0893998 --- /dev/null +++ b/docs/examples/datatype_object.md @@ -0,0 +1,5 @@ +# An HDF5 Datatype Object + +```{literalinclude} datatype_object.json +:language: json +``` diff --git a/docs/examples/datatype_object.rst b/docs/examples/datatype_object.rst deleted file mode 100644 index 4676d1d..0000000 --- a/docs/examples/datatype_object.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Datatype Object -======================= - -.. literalinclude:: datatype_object.json - :language: json diff --git a/docs/examples/empty.md b/docs/examples/empty.md new file mode 100644 index 0000000..6b58d49 --- /dev/null +++ b/docs/examples/empty.md @@ -0,0 +1,5 @@ +# An "empty" HDF5 File + +```{literalinclude} empty.json +:language: json +``` diff --git a/docs/examples/empty.rst b/docs/examples/empty.rst deleted file mode 100644 index cde2353..0000000 --- a/docs/examples/empty.rst +++ /dev/null @@ -1,5 +0,0 @@ -An "empty" HDF5 File -==================== - -.. literalinclude:: empty.json - :language: json diff --git a/docs/examples/enum_attr.md b/docs/examples/enum_attr.md new file mode 100644 index 0000000..807b047 --- /dev/null +++ b/docs/examples/enum_attr.md @@ -0,0 +1,5 @@ +# An HDF5 Enumerated Datatype (Attribute) + +```{literalinclude} enum_attr.json +:language: json +``` diff --git a/docs/examples/enum_attr.rst b/docs/examples/enum_attr.rst deleted file mode 100644 index 5a87a8a..0000000 --- a/docs/examples/enum_attr.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Enumerated Datatype (Attribute) -======================================= - -.. literalinclude:: enum_attr.json - :language: json diff --git a/docs/examples/fixed_string_dset.md b/docs/examples/fixed_string_dset.md new file mode 100644 index 0000000..09501a9 --- /dev/null +++ b/docs/examples/fixed_string_dset.md @@ -0,0 +1,5 @@ +# An HDF5 Fixed-Length String Datatype (Dataset) + +```{literalinclude} fixed_string_dset.json +:language: json +``` diff --git a/docs/examples/fixed_string_dset.rst b/docs/examples/fixed_string_dset.rst deleted file mode 100644 index 40db043..0000000 --- a/docs/examples/fixed_string_dset.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Fixed-Length String Datatype (Dataset) -============================================== - -.. literalinclude:: fixed_string_dset.json - :language: json diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 0000000..7714cfc --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,23 @@ +# Examples + +File content examples in HDF5/JSON. + +```{toctree} +classic +array_dset +compound +datatype_object +empty +enum_attr +fixed_string_dset +null_objref_dset +nullspace_dset +objref_attr +regionref_attr +resizable +scalar +tall +tgroup +vlen_dset +vlen_string_attr +``` diff --git a/docs/examples/index.rst b/docs/examples/index.rst deleted file mode 100644 index 3f8eb56..0000000 --- a/docs/examples/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -Examples -======== - -File content examples in HDF5/JSON. - -.. toctree:: - - classic - array_dset - compound - datatype_object - empty - enum_attr - fixed_string_dset - null_objref_dset - nullspace_dset - objref_attr - regionref_attr - resizable - scalar - tall - tgroup - vlen_dset - vlen_string_attr diff --git a/docs/examples/null_objref_dset.md b/docs/examples/null_objref_dset.md new file mode 100644 index 0000000..2bcc614 --- /dev/null +++ b/docs/examples/null_objref_dset.md @@ -0,0 +1,5 @@ +# An HDF5 Uninitialized HDF5 Object Reference + +```{literalinclude} null_objref_dset.json +:language: json +``` diff --git a/docs/examples/null_objref_dset.rst b/docs/examples/null_objref_dset.rst deleted file mode 100644 index 36d70ea..0000000 --- a/docs/examples/null_objref_dset.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Uninitialized HDF5 Object Reference -=========================================== - -.. literalinclude:: null_objref_dset.json - :language: json diff --git a/docs/examples/nullspace_dset.md b/docs/examples/nullspace_dset.md new file mode 100644 index 0000000..58759c6 --- /dev/null +++ b/docs/examples/nullspace_dset.md @@ -0,0 +1,5 @@ +# An HDF5 Dataset with an HDF5 NULL Dataspace + +```{literalinclude} nullspace_dset.json +:language: json +``` diff --git a/docs/examples/nullspace_dset.rst b/docs/examples/nullspace_dset.rst deleted file mode 100644 index 7e8c118..0000000 --- a/docs/examples/nullspace_dset.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Dataset with an HDF5 NULL Dataspace -=========================================== - -.. literalinclude:: nullspace_dset.json - :language: json diff --git a/docs/examples/objref_attr.md b/docs/examples/objref_attr.md new file mode 100644 index 0000000..82eb394 --- /dev/null +++ b/docs/examples/objref_attr.md @@ -0,0 +1,5 @@ +# An HDF5 Object Reference Datatype (Attribute) + +```{literalinclude} objref_attr.json +:language: json +``` diff --git a/docs/examples/objref_attr.rst b/docs/examples/objref_attr.rst deleted file mode 100644 index 72732e5..0000000 --- a/docs/examples/objref_attr.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Object Reference Datatype (Attribute) -============================================= - -.. literalinclude:: objref_attr.json - :language: json diff --git a/docs/examples/regionref_attr.md b/docs/examples/regionref_attr.md new file mode 100644 index 0000000..5d76064 --- /dev/null +++ b/docs/examples/regionref_attr.md @@ -0,0 +1,5 @@ +# An HDF5 Region Reference Datatype (Attribute) + +```{literalinclude} regionref_attr.json +:language: json +``` diff --git a/docs/examples/regionref_attr.rst b/docs/examples/regionref_attr.rst deleted file mode 100644 index 149b8f0..0000000 --- a/docs/examples/regionref_attr.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 Region Reference Datatype (Attribute) -============================================= - -.. literalinclude:: regionref_attr.json - :language: json diff --git a/docs/examples/resizable.md b/docs/examples/resizable.md new file mode 100644 index 0000000..bd99ae1 --- /dev/null +++ b/docs/examples/resizable.md @@ -0,0 +1,5 @@ +# A resizable HDF5 Dataset + +```{literalinclude} resizable.json +:language: json +``` diff --git a/docs/examples/resizable.rst b/docs/examples/resizable.rst deleted file mode 100644 index b11fc2e..0000000 --- a/docs/examples/resizable.rst +++ /dev/null @@ -1,5 +0,0 @@ -A resizable HDF5 Dataset -======================== - -.. literalinclude:: resizable.json - :language: json diff --git a/docs/examples/scalar.md b/docs/examples/scalar.md new file mode 100644 index 0000000..2995f5e --- /dev/null +++ b/docs/examples/scalar.md @@ -0,0 +1,5 @@ +# HDF5 scalar Datasets and Attributes + +```{literalinclude} scalar.json +:language: json +``` diff --git a/docs/examples/scalar.rst b/docs/examples/scalar.rst deleted file mode 100644 index 2385010..0000000 --- a/docs/examples/scalar.rst +++ /dev/null @@ -1,5 +0,0 @@ -HDF5 scalar Datasets and Attributes -=================================== - -.. literalinclude:: scalar.json - :language: json diff --git a/docs/examples/tall.md b/docs/examples/tall.md new file mode 100644 index 0000000..e5089d9 --- /dev/null +++ b/docs/examples/tall.md @@ -0,0 +1,5 @@ +# A sample File + +```{literalinclude} tall.json +:language: json +``` diff --git a/docs/examples/tall.rst b/docs/examples/tall.rst deleted file mode 100644 index c9819a7..0000000 --- a/docs/examples/tall.rst +++ /dev/null @@ -1,5 +0,0 @@ -A sample File -============= - -.. literalinclude:: tall.json - :language: json diff --git a/docs/examples/tgroup.md b/docs/examples/tgroup.md new file mode 100644 index 0000000..21f2e48 --- /dev/null +++ b/docs/examples/tgroup.md @@ -0,0 +1,5 @@ +# A few HDF5 Groups + +```{literalinclude} tgroup.json +:language: json +``` diff --git a/docs/examples/tgroup.rst b/docs/examples/tgroup.rst deleted file mode 100644 index 83d54d0..0000000 --- a/docs/examples/tgroup.rst +++ /dev/null @@ -1,5 +0,0 @@ -A few HDF5 Groups -================= - -.. literalinclude:: tgroup.json - :language: json diff --git a/docs/examples/vlen_dset.md b/docs/examples/vlen_dset.md new file mode 100644 index 0000000..e726cf1 --- /dev/null +++ b/docs/examples/vlen_dset.md @@ -0,0 +1,5 @@ +# An HDF5 variable-length Datatype (Dataset) + +```{literalinclude} vlen_dset.json +:language: json +``` diff --git a/docs/examples/vlen_dset.rst b/docs/examples/vlen_dset.rst deleted file mode 100644 index b8bcfe8..0000000 --- a/docs/examples/vlen_dset.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 variable-length Datatype (Dataset) -========================================== - -.. literalinclude:: vlen_dset.json - :language: json diff --git a/docs/examples/vlen_string_attr.md b/docs/examples/vlen_string_attr.md new file mode 100644 index 0000000..a808799 --- /dev/null +++ b/docs/examples/vlen_string_attr.md @@ -0,0 +1,5 @@ +# An HDF5 variable-length String Datatype (Attribute) + +```{literalinclude} vlen_string_attr.json +:language: json +``` diff --git a/docs/examples/vlen_string_attr.rst b/docs/examples/vlen_string_attr.rst deleted file mode 100644 index 9ceff1d..0000000 --- a/docs/examples/vlen_string_attr.rst +++ /dev/null @@ -1,5 +0,0 @@ -An HDF5 variable-length String Datatype (Attribute) -=================================================== - -.. literalinclude:: vlen_string_attr.json - :language: json diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8aa012a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +# HDF5/JSON + +Specification for representation and tools for manipulation of HDF5 content in +JSON by the [HDF Group](https://www.hdfgroup.org). + +What is Here: + +```{toctree} +:maxdepth: 2 + +specs +examples/index +tools/h5json +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index f81c329..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -HDF5/JSON -========= - -Specification for representation and tools for manipulation of HDF5 content in -JSON by the `HDF Group `_. - -What is Here: - -.. toctree:: - :maxdepth: 2 - - specs - examples/index - tools/h5json diff --git a/docs/requirements.txt b/docs/requirements.txt index b880117..865ddbe 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ file:.#egg=h5json sphinx-book-theme +sphinx-copybutton diff --git a/docs/schema/attribute.md b/docs/schema/attribute.md new file mode 100644 index 0000000..dffaed0 --- /dev/null +++ b/docs/schema/attribute.md @@ -0,0 +1,5 @@ +# Attribute + +```{literalinclude} ../../h5json/schema/attribute.schema.json +:language: json +``` diff --git a/docs/schema/attribute.rst b/docs/schema/attribute.rst deleted file mode 100644 index 90d0342..0000000 --- a/docs/schema/attribute.rst +++ /dev/null @@ -1,5 +0,0 @@ -Attribute -========= - -.. literalinclude:: ../../h5json/schema/attribute.schema.json - :language: json diff --git a/docs/schema/dataset.md b/docs/schema/dataset.md new file mode 100644 index 0000000..9d544e2 --- /dev/null +++ b/docs/schema/dataset.md @@ -0,0 +1,5 @@ +# Dataset + +```{literalinclude} ../../h5json/schema/dataset.schema.json +:language: json +``` diff --git a/docs/schema/dataset.rst b/docs/schema/dataset.rst deleted file mode 100644 index a87a2fa..0000000 --- a/docs/schema/dataset.rst +++ /dev/null @@ -1,5 +0,0 @@ -Dataset -======= - -.. literalinclude:: ../../h5json/schema/dataset.schema.json - :language: json diff --git a/docs/schema/dataspaces.md b/docs/schema/dataspaces.md new file mode 100644 index 0000000..8556c57 --- /dev/null +++ b/docs/schema/dataspaces.md @@ -0,0 +1,5 @@ +# Dataspace + +```{literalinclude} ../../h5json/schema/dataspaces.schema.json +:language: json +``` diff --git a/docs/schema/dataspaces.rst b/docs/schema/dataspaces.rst deleted file mode 100644 index 5a00c9b..0000000 --- a/docs/schema/dataspaces.rst +++ /dev/null @@ -1,5 +0,0 @@ -Dataspace -========= - -.. literalinclude:: ../../h5json/schema/dataspaces.schema.json - :language: json diff --git a/docs/schema/datatypes.md b/docs/schema/datatypes.md new file mode 100644 index 0000000..4deb193 --- /dev/null +++ b/docs/schema/datatypes.md @@ -0,0 +1,5 @@ +# Datatype + +```{literalinclude} ../../h5json/schema/datatypes.schema.json +:language: json +``` diff --git a/docs/schema/datatypes.rst b/docs/schema/datatypes.rst deleted file mode 100644 index 4b6f6b4..0000000 --- a/docs/schema/datatypes.rst +++ /dev/null @@ -1,5 +0,0 @@ -Datatype -======== - -.. literalinclude:: ../../h5json/schema/datatypes.schema.json - :language: json diff --git a/docs/schema/file.md b/docs/schema/file.md new file mode 100644 index 0000000..649fa55 --- /dev/null +++ b/docs/schema/file.md @@ -0,0 +1,7 @@ +# File + +Main schema, describing the overall file content as HDF5/JSON. + +```{literalinclude} ../../h5json/schema/hdf5.schema.json +:language: json +``` diff --git a/docs/schema/file.rst b/docs/schema/file.rst deleted file mode 100644 index ebca784..0000000 --- a/docs/schema/file.rst +++ /dev/null @@ -1,7 +0,0 @@ -File -==== - -Main schema, describing the overall file content as HDF5/JSON. - -.. literalinclude:: ../../h5json/schema/hdf5.schema.json - :language: json diff --git a/docs/schema/filters.md b/docs/schema/filters.md new file mode 100644 index 0000000..2f84d0d --- /dev/null +++ b/docs/schema/filters.md @@ -0,0 +1,5 @@ +# Filter + +```{literalinclude} ../../h5json/schema/filters.schema.json +:language: json +``` diff --git a/docs/schema/filters.rst b/docs/schema/filters.rst deleted file mode 100644 index a360654..0000000 --- a/docs/schema/filters.rst +++ /dev/null @@ -1,5 +0,0 @@ -Filter -====== - -.. literalinclude:: ../../h5json/schema/filters.schema.json - :language: json diff --git a/docs/schema/group.md b/docs/schema/group.md new file mode 100644 index 0000000..a65ed8c --- /dev/null +++ b/docs/schema/group.md @@ -0,0 +1,5 @@ +# Group + +```{literalinclude} ../../h5json/schema/group.schema.json +:language: json +``` diff --git a/docs/schema/group.rst b/docs/schema/group.rst deleted file mode 100644 index 4904e53..0000000 --- a/docs/schema/group.rst +++ /dev/null @@ -1,5 +0,0 @@ -Group -===== - -.. literalinclude:: ../../h5json/schema/group.schema.json - :language: json diff --git a/docs/schema/index.md b/docs/schema/index.md new file mode 100644 index 0000000..b22c6bc --- /dev/null +++ b/docs/schema/index.md @@ -0,0 +1,15 @@ +# JSON Schema + +HDF5/JSON specification as JSON Schema. + +```{toctree} +:maxdepth: 1 + +file +group +dataset +datatypes +dataspaces +attribute +filters +``` diff --git a/docs/schema/index.rst b/docs/schema/index.rst deleted file mode 100644 index 2616507..0000000 --- a/docs/schema/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -JSON Schema -=========== - -HDF5/JSON specification as JSON Schema. - -.. toctree:: - :maxdepth: 1 - - file - group - dataset - datatypes - dataspaces - attribute - filters diff --git a/docs/specs.md b/docs/specs.md new file mode 100644 index 0000000..ea2e32c --- /dev/null +++ b/docs/specs.md @@ -0,0 +1,8 @@ +# Specification + +```{toctree} +:maxdepth: 1 + +bnf/index +schema/index +``` diff --git a/docs/specs.rst b/docs/specs.rst deleted file mode 100644 index a3ac0b5..0000000 --- a/docs/specs.rst +++ /dev/null @@ -1,8 +0,0 @@ -Specification -============= - -.. toctree:: - :maxdepth: 1 - - bnf/index - schema/index diff --git a/docs/tools/h5json.md b/docs/tools/h5json.md new file mode 100644 index 0000000..c3d1185 --- /dev/null +++ b/docs/tools/h5json.md @@ -0,0 +1,136 @@ +# h5json Package + +This package provides CLI tools for conversion between HDF5 files and HDF5/JSON, +and HDF5/JSON validation. + +## Installation + +The standard method using the *pip* tool is recommended: + +``` +pip install h5json +``` + +If interested in an unreleased version, install directly from the repository: + +``` +pip install git+https://github.com/HDFGroup/hdf5-json.git@{LABEL} +``` + +`{LABEL}` is a branch, tag, or commit identifier. *pip* [documentation](https://pip.pypa.io/en/stable/cli/pip_install/#pip-install-examples) explains +available install features. + +For development, create a fork of the [repository](https://github.com/HDFGroup/hdf5-json.git) and execute: + +```shell +$ mkdir my-h5json-dev +$ cd my-h5json-dev +$ git clone https://{MYUSERNAME}@github.com/{MYUSERNAME}/hdf5-json.git +$ cd h5json +$ pip install -e . +``` + +[GitHub documentation](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories) +explains this workflow in great detail. + +### Verification + +To verify h5json was installed correctly convert an HDF5 file to HDF5/JSON and +back. Run the following commands: + +```shell +$ h5tojson sample.h5 > sample.json +$ h5jvalidate sample.json +$ jsontoh5 sample.json new-sample.h5 +``` + +The file `sample.json` should contain HDF5/JSON description of the original +file and the file `new-sample.h5` should be an HDF5 equivalent to the original +file `sample.h5`. + +## CLI Tools + +The h5json distribution provides three command-line tools described below. + +### jsontoh5 + +Generate an HDF5 file with the content, storage features, and data described in +an HDF5/JSON file. + +Usage: + +``` +jsontoh5.py [-h] +``` + +where: + +`` + +: Input HDF5/JSON file. + +`` + +: Output HDF5 file that will be created. + +Options: + +`-h` + +: Print help message. + +### h5tojson + +Convert the input HDF5 file to its HDF5/JSON representation. Output is printed +to `stdout`. + +Usage: + +``` +h5tojson [-h] [-D] [-d] +``` + +where: + +`` + +: HDF5 file. + +Options: + +`-h` +: Print help message. + +`-D` +: Suppress all data output. Output HDF5/JSON will not contain any dataset or +attribute values. + +`-d` +: Suppress data output for datasets only. + +### h5jvalidate + +Validate generated HDF5/JSON files against the schema. Validation errors are +printed to `stderr`. Command's exit status indicates the overall success (`0`) +or failure (`1`). + +Usage: + +``` +h5jvalidate [-h|--help] [-s|--stop] JSON_LOC [JSON_LOC ...] +``` + +where: + +`JSON_LOC` + +: HDF5/JSON location (files or folders). If a folder, all files with `.json` + extension will be selected for validation. + +Options: + +`-s`, `--stop` +: Stop after first HDF5/JSON file failed validation (default: False) + +`-h`, `--help` +: Print help message. diff --git a/docs/tools/h5json.rst b/docs/tools/h5json.rst deleted file mode 100755 index 8fbed3a..0000000 --- a/docs/tools/h5json.rst +++ /dev/null @@ -1,129 +0,0 @@ -############## -h5json Package -############## - -This package provides CLI tools for conversion between HDF5 files and HDF5/JSON, -and HDF5/JSON validation. - -Installation -============ - -The standard method using the *pip* tool is recommended:: - - pip install h5json - -If interested in an unreleased version, install directly from the repository:: - - pip install git+https://github.com/HDFGroup/hdf5-json.git@{LABEL} - -``{LABEL}`` is a branch, tag, or commit identifier. *pip* `documentation -`_ explains -available install features. - -For development, create a fork of the `repository -`_ and execute:: - - $ mkdir my-h5json-dev - $ cd my-h5json-dev - $ git clone https://{MYUSERNAME}@github.com/{MYUSERNAME}/hdf5-json.git - $ cd h5json - $ pip install -e . - -`GitHub documentation -`_ -explains this workflow in great detail. - -Verification ------------- - -To verify h5json was installed correctly convert an HDF5 file to HDF5/JSON and -back. Run the following commands: - -.. code-block:: shell - - $ h5tojson sample.h5 > sample.json - $ h5jvalidate sample.json - $ jsontoh5 sample.json new-sample.h5 - -The file ``sample.json`` should contain HDF5/JSON description of the original -file and the file ``new-sample.h5`` should be an HDF5 equivalent to the original -file ``sample.h5``. - - -CLI Tools -========= - -The h5json distribution provides three command-line tools described below. - -jsontoh5 --------- - -Generate an HDF5 file with the content, storage features, and data described in -an HDF5/JSON file. - -Usage:: - - jsontoh5.py [-h] - -where: - -```` - Input HDF5/JSON file. - -```` - Output HDF5 file that will be created. - -Options: - --h - Print help message. - -h5tojson --------- - -Convert the input HDF5 file to its HDF5/JSON representation. Output is printed -to `stdout`. - -Usage:: - - h5tojson [-h] [-D] [-d] - -where: - -```` - HDF5 file. - -Options: - --h - Print help message. --D - Suppress all data output. Output HDF5/JSON will not contain any dataset or - attribute values. --d - Suppress data output for datasets only. - - -h5jvalidate ------------ - -Validate generated HDF5/JSON files against the schema. Validation errors are -printed to `stderr`. Command's exit status indicates the overall success (``0``) -or failure (``1``). - -Usage:: - - h5jvalidate [-h|--help] [-s|--stop] JSON_LOC [JSON_LOC ...] - -where: - -``JSON_LOC`` - HDF5/JSON location (files or folders). If a folder, all files with ``.json`` - extension will be selected for validation. - -Options: - --s, --stop - Stop after first HDF5/JSON file failed validation (default: False) --h, --help - Print help message.