Fix datatype documentation (#1108)

* Fix datatype documentations * Add additional resources page * Actually add resources.md
JuliaIO · Sep 6, 2023 · 6afbafb · 6afbafb · mkitti · Sep 6, 2023
1 parent 1f65f4d
commit 6afbafb
Show file tree

Hide file tree

Showing 5 changed files with 77 additions and 27 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -1,8 +1,8 @@
 # This file is machine-generated - editing it directly is not advised
 
-julia_version = "1.9.0"
+julia_version = "1.9.3"
 manifest_format = "2.0"
-project_hash = "b82c9c318ab556c33f5a67f1e314caaa8d7804ae"
+project_hash = "2d4ae38483c05e04907e6c281e51323f031e5f7e"
 
 [[deps.ANSIColoredPrinters]]
 git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
@@ -62,9 +62,9 @@ version = "0.7.2"
 
 [[deps.Compat]]
 deps = ["UUIDs"]
-git-tree-sha1 = "4e88377ae7ebeaf29a047aa1ee40826e0b708a5d"
+git-tree-sha1 = "e460f044ca8b99be31d35fe54fc33a5c33dd8ed7"
 uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
-version = "4.7.0"
+version = "4.9.0"
 
     [deps.Compat.extensions]
     CompatLinearAlgebraExt = "LinearAlgebra"
@@ -76,7 +76,7 @@ version = "4.7.0"
 [[deps.CompilerSupportLibraries_jll]]
 deps = ["Artifacts", "Libdl"]
 uuid = "e66e0078-7015-5450-92f7-15fbd957f2ae"
-version = "1.0.2+0"
+version = "1.0.5+0"
 
 [[deps.Dates]]
 deps = ["Printf"]
@@ -112,6 +112,12 @@ version = "1.6.0"
 [[deps.FileWatching]]
 uuid = "7b1f6079-737a-58dc-b8bc-7a2ca5c1b5ee"
 
+[[deps.H5Zbitshuffle]]
+deps = ["HDF5", "bitshuffle_jll"]
+path = "../filters/H5Zbitshuffle"
+uuid = "51b4e782-877f-4ccf-958a-27bf628210da"
+version = "0.1.1"
+
 [[deps.H5Zblosc]]
 deps = ["Blosc", "HDF5"]
 path = "../filters/H5Zblosc"
@@ -148,9 +154,9 @@ weakdeps = ["MPI"]
 
 [[deps.HDF5_jll]]
 deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LLVMOpenMP_jll", "LazyArtifacts", "LibCURL_jll", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "OpenSSL_jll", "TOML", "Zlib_jll", "libaec_jll"]
-git-tree-sha1 = "3b20c3ce9c14aedd0adca2bc8c882927844bd53d"
+git-tree-sha1 = "10c72358aaaa5cd6bc7cc39b95e6eadf92f5a336"
 uuid = "0234f1f7-429e-5d53-9886-15a909be8d59"
-version = "1.14.0+0"
+version = "1.14.2+0"
 
 [[deps.IOCapture]]
 deps = ["Logging", "Random"]
@@ -163,10 +169,10 @@ deps = ["Markdown"]
 uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 
 [[deps.JLLWrappers]]
-deps = ["Preferences"]
-git-tree-sha1 = "abc9885a7ca2052a736a600f7fa66209f96506e1"
+deps = ["Artifacts", "Preferences"]
+git-tree-sha1 = "7e5d6779a1e09a36db2a7b6cff50942a0a7d0fca"
 uuid = "692b3bcd-3c85-4b1f-b108-f13ce0eb3210"
-version = "1.4.1"
+version = "1.5.0"
 
 [[deps.JSON]]
 deps = ["Dates", "Mmap", "Parsers", "Unicode"]
@@ -210,16 +216,16 @@ uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
 
 [[deps.Lz4_jll]]
-deps = ["Artifacts", "JLLWrappers", "Libdl", "Pkg"]
-git-tree-sha1 = "5d494bc6e85c4c9b626ee0cab05daa4085486ab1"
+deps = ["Artifacts", "JLLWrappers", "Libdl"]
+git-tree-sha1 = "6c26c5e8a4203d43b5497be3ec5d4e0c3cde240a"
 uuid = "5ced341a-0733-55b8-9ab6-a4889d929147"
-version = "1.9.3+0"
+version = "1.9.4+0"
 
 [[deps.MPI]]
 deps = ["Distributed", "DocStringExtensions", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenMPI_jll", "PkgVersion", "PrecompileTools", "Requires", "Serialization", "Sockets"]
-git-tree-sha1 = "98fc280a56d3b5cc218435f82df60e05771fefa6"
+git-tree-sha1 = "32cafbe56c7f0b7160a1a6c492773af66c0b722f"
 uuid = "da04e1cc-30fd-572f-bb4f-1f8673147195"
-version = "0.20.12"
+version = "0.20.14"
 
     [deps.MPI.extensions]
     AMDGPUExt = "AMDGPU"
@@ -237,9 +243,9 @@ version = "4.1.2+0"
 
 [[deps.MPIPreferences]]
 deps = ["Libdl", "Preferences"]
-git-tree-sha1 = "d86a788b336e8ae96429c0c42740ccd60ac0dfcc"
+git-tree-sha1 = "781916a2ebf2841467cda03b6f1af43e23839d85"
 uuid = "3da0fdf6-3ccc-4f1b-acd9-58baa6c99267"
-version = "0.1.8"
+version = "0.1.9"
 
 [[deps.MPItrampoline_jll]]
 deps = ["Artifacts", "CompilerSupportLibraries_jll", "JLLWrappers", "LazyArtifacts", "Libdl", "MPIPreferences", "TOML"]
@@ -281,32 +287,32 @@ version = "4.1.5+0"
 
 [[deps.OpenSSL_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl"]
-git-tree-sha1 = "cae3153c7f6cf3f069a853883fd1919a6e5bab5b"
+git-tree-sha1 = "e78db7bd5c26fc5a6911b50a47ee302219157ea8"
 uuid = "458c3c95-2e84-50aa-8efc-19380b2a3a95"
-version = "3.0.9+0"
+version = "3.0.10+0"
 
 [[deps.Parsers]]
 deps = ["Dates", "PrecompileTools", "UUIDs"]
-git-tree-sha1 = "4b2e829ee66d4218e0cef22c0a64ee37cf258c29"
+git-tree-sha1 = "716e24b21538abc91f6205fd1d8363f39b442851"
 uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
-version = "2.7.1"
+version = "2.7.2"
 
 [[deps.Pkg]]
 deps = ["Artifacts", "Dates", "Downloads", "FileWatching", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "Serialization", "TOML", "Tar", "UUIDs", "p7zip_jll"]
 uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
-version = "1.9.0"
+version = "1.9.2"
 
 [[deps.PkgVersion]]
 deps = ["Pkg"]
-git-tree-sha1 = "f6cf8e7944e50901594838951729a1861e668cb8"
+git-tree-sha1 = "f9501cc0430a26bc3d156ae1b5b0c1b47af4d6da"
 uuid = "eebad327-c553-4316-9ea0-9fa01ccd7688"
-version = "0.3.2"
+version = "0.3.3"
 
 [[deps.PrecompileTools]]
 deps = ["Preferences"]
-git-tree-sha1 = "9673d39decc5feece56ef3940e5dafba15ba0f81"
+git-tree-sha1 = "03b4c25b43cb84cee5c90aa9b5ea0a78fd848d2f"
 uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
-version = "1.1.2"
+version = "1.2.0"
 
 [[deps.Preferences]]
 deps = ["TOML"]
@@ -380,6 +386,12 @@ git-tree-sha1 = "49ce682769cd5de6c72dcf1b94ed7790cd08974c"
 uuid = "3161d3a3-bdf6-5164-811a-617609db77b4"
 version = "1.5.5+0"
 
+[[deps.bitshuffle_jll]]
+deps = ["Artifacts", "JLLWrappers", "Libdl", "Lz4_jll", "Pkg", "Zstd_jll"]
+git-tree-sha1 = "fc80beaec46263a31471fe2f14f5a0d9bea05c4c"
+uuid = "228fe19c-1b83-5282-a626-13744502a320"
+version = "0.4.2+0"
+
 [[deps.libaec_jll]]
 deps = ["Artifacts", "JLLWrappers", "Libdl"]
 git-tree-sha1 = "eddd19a8dea6b139ea97bdc8a0e2667d4b661720"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,6 +1,7 @@
 [deps]
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+H5Zbitshuffle = "51b4e782-877f-4ccf-958a-27bf628210da"
 H5Zblosc = "c8ec2601-a99c-407f-b158-e79c03c2f5f7"
 H5Zbzip2 = "094576f2-1e46-4c84-8e32-c46c042eaaa2"
 H5Zlz4 = "eb20ec05-5464-47b5-ba41-098e3c1068a3"

diff --git a/docs/make.jl b/docs/make.jl
@@ -45,6 +45,7 @@ makedocs(;
         ],
         "mpi.md",
         "Low-level library bindings" => "api_bindings.md",
+        "Additional Resources" => "resources.md",
     ]
 )
 

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -1,5 +1,8 @@
 ```@meta
 CurrentModule = HDF5
+DocTestSetup = quote
+    using HDF5
+end
 ```
 
 # HDF5.jl
@@ -334,12 +337,29 @@ mtx = HDF5.readmmap(mtx_dset) # succeeds immediately
 
 ## Supported data types
 
-`HDF5.jl` knows how to store values of the following types: signed and unsigned integers of 8, 16, 32, and 64 bits, `Float32`, `Float64`; `Complex` versions of these numeric types; `Array`s of these numeric types (including complex versions); `ASCIIString` and `UTF8String`; and `Array`s of these two string types.
+`HDF5.jl` knows how to store values of the following types: signed and unsigned integers of 8, 16, 32, and 64 bits, `Float32`, `Float64`; `Complex` versions of these numeric types; `Array`s of these numeric types (including complex versions); `String`; and `Array`s of `String`.
 `Array`s of strings are supported using HDF5's variable-length-strings facility.
 By default `Complex` numbers are stored as compound types with `r` and `i` fields following the `h5py` convention.
 When reading data, compound types with matching field names will be loaded as the corresponding `Complex` Julia type.
 These field names are configurable with the `HDF5.set_complex_field_names(real::AbstractString, imag::AbstractString)` function and complex support can be completely enabled/disabled with `HDF5.enable/disable_complex_support()`.
 
+As of HDF5.jl version 0.16.13, support was added to map Julia structs to compound HDF5 datatypes.
+
+```jldoctest
+julia> struct Point3{T}
+           x::T
+           y::T
+           z::T
+       end
+
+julia> datatype(Point3{Float64})
+HDF5.Datatype: H5T_COMPOUND {
+      H5T_IEEE_F64LE "x" : 0;
+      H5T_IEEE_F64LE "y" : 8;
+      H5T_IEEE_F64LE "z" : 16;
+   }
+```
+
 For `Array`s, note that the array dimensionality is preserved, including 0-length
 dimensions:
 

diff --git a/docs/src/resources.md b/docs/src/resources.md
@@ -0,0 +1,16 @@
+# Additional Resources
+
+## JuliaCon 2023 Presentation
+
+During JuliaCon 2023, Mark Kittisopikul and Simon Byrne presented "HDF5.jl: Hierarchial Data Storage for Julia" with assistance from Mustafa Mohamad. A recording of the talk is available on YouTube below.
+
+```@raw html
+<iframe width="560" height="315" src="https://www.youtube.com/embed/YNDDB8uR26Q?si=V5ArUwOkG6s7VesL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+```
+
+The slides for the JuliaCon 2023 presentation are also available [download](https://github.com/JuliaIO/HDF5.jl/blob/master/docs/juliacon_2023/juliacon_2023_presentation.pdf).
+
+## Community Help Channels
+
+* The Julia Discourse forum has a [hdf5 tag](https://discourse.julialang.org/tag/hdf5)
+* The [Julia Community](https://julialang.org/community/) also has a number of chat options. See the [#data](https://julialang.slack.com/archives/C674VR0HH) or [#helpdesk](https://julialang.slack.com/archives/C6A044SQH) chat channels.