Fix formatting, docs. Import rather than alias symbols.

JuliaIO · Jul 1, 2024 · 4ba2c22 · 4ba2c22
1 parent 3c23e3c
commit 4ba2c22
Show file tree

Hide file tree

Showing 9 changed files with 232 additions and 118 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
diff --git a/docs/make.jl b/docs/make.jl
@@ -4,21 +4,34 @@ using H5Zblosc
 using H5Zbzip2
 using H5Zlz4
 using H5Zzstd
+using H5Zbitshuffle
 using MPI  # needed to generate docs for parallel HDF5 API
 
 DocMeta.setdocmeta!(HDF5, :DocTestSetup, :(using HDF5); recursive=true)
 
 makedocs(;
     sitename="HDF5.jl",
-    modules=[HDF5, H5Zblosc, H5Zbzip2, H5Zlz4, H5Zzstd],
+    modules=[
+        HDF5,
+        H5Zblosc,
+        H5Zbzip2,
+        H5Zlz4,
+        H5Zzstd,
+        H5Zbitshuffle,
+        Base.get_extension(HDF5, :BloscExt),
+        Base.get_extension(HDF5, :CodecBzip2Ext),
+        Base.get_extension(HDF5, :CodecLz4Ext),
+        Base.get_extension(HDF5, :CodecZstdExt),
+        Base.get_extension(HDF5, :bitshuffle_jll_ext),
+    ],
     authors="Mustafa Mohamad <[email protected]> and contributors",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://JuliaIO.github.io/HDF5.jl",
         assets=String[],
-        sidebar_sitename=false
+        sidebar_sitename=false,
+        size_threshold_ignore=["api_bindings.md",]
     ),
-    strict=true,
     pages=[
         "Home" => "index.md",
         "Interface" => [

diff --git a/docs/src/interface/filters.md b/docs/src/interface/filters.md
@@ -39,12 +39,29 @@ Several external Julia packages implement HDF5 filter plugins in Julia.
 As they are independent of HDF5.jl, they must be installed in order to use their plugins.
 
 The
+[H5Zbitshuffle.jl](https://github.com/JuliaIO/HDF5.jl/tree/master/filters/H5Zbitshuffle),
 [H5Zblosc.jl](https://github.com/JuliaIO/HDF5.jl/tree/master/filters/H5Zblosc),
 [H5Zbzip2.jl](https://github.com/JuliaIO/HDF5.jl/tree/master/filters/H5Zbzip2),
 [H5Zlz4.jl](https://github.com/JuliaIO/HDF5.jl/tree/master/filters/H5Zlz4), and
 [H5Zzstd.jl](https://github.com/JuliaIO/HDF5.jl/tree/master/filters/H5Zzstd) packages are maintained as
 independent subdirectory packages within the HDF5.jl repository.
 
+### Extension packages
+
+For Julia 1.9 and greater, the external filter packages listed above at version 0.2 and greater are loose wrappers around extension packages. The filter extension packages currently implemented are as follows:
+* bitshuffle_jll_ext
+* H5Zblosc_ext
+* H5Zbzip2_ext
+* H5Zlz4_ext
+* H5Zzstd_ext
+
+```
+using HDF5, CodecZstd
+const CodecZstdExt = Base.get_extension(HDF5, :CodecZstdExt)
+using .CodecZstdExt
+filter = ZstdFilter(5)
+```
+
 ### H5Zblosc.jl
 
 ```@meta
@@ -83,6 +100,19 @@ CurrentModule = H5Zzstd
 
 ```@docs
 ZstdFilter
+H5Zzstd
+```
+
+### H5Zbitshuffle
+
+```@meta
+CurrentModule = H5Zbitshuffle
+```
+
+```@docs
+BitshuffleFilter
+H5Zbitshuffle
+bitshuffle_jll_ext
 ```
 
 ## Other External Filters

diff --git a/filters/H5Zbitshuffle/src/.H5Zbitshuffle.jl.swp b/filters/H5Zbitshuffle/src/.H5Zbitshuffle.jl.swp
diff --git a/filters/H5Zbitshuffle/src/H5Zbitshuffle.jl b/filters/H5Zbitshuffle/src/H5Zbitshuffle.jl
@@ -10,6 +10,7 @@ module H5Zbitshuffle
 using bitshuffle_jll
 
 using HDF5: HDF5
+# The next block of lines can be removed
 using HDF5.API
 import HDF5.Filters:
     Filter,
@@ -26,19 +27,19 @@ export BSHUF_H5_COMPRESS_LZ4,
 
 const bitshuffle_jll_ext = Base.get_extension(HDF5, :bitshuffle_jll_ext)
 
-const BSHUF_H5_COMPRESS_LZ4 = bitshuffle_jll_ext.BSHUF_H5_COMPRESS_LZ4
-const BSHUF_H5_COMPRESS_ZSTD = bitshuffle_jll_ext.BSHUF_H5_COMPRESS_ZSTD
-const BitshuffleFilter = bitshuffle_jll_ext.BitshuffleFilter
-const H5Z_filter_bitshuffle = bitshuffle_jll_ext.H5Z_filter_bitshuffle
+using .bitshuffle_jll_ext: BSHUF_H5_COMPRESS_LZ4
+using .bitshuffle_jll_ext: BSHUF_H5_COMPRESS_ZSTD
+using .bitshuffle_jll_ext: BitshuffleFilter
+using .bitshuffle_jll_ext: H5Z_filter_bitshuffle
 
-const BSHUF_H5_COMPRESS_LZ4 = bitshuffle_jll_ext.BSHUF_H5_COMPRESS_LZ4
-const BSHUF_H5_COMPRESS_ZSTD = bitshuffle_jll_ext.BSHUF_H5_COMPRESS_ZSTD
-const H5Z_FILTER_BITSHUFFLE = bitshuffle_jll_ext.H5Z_FILTER_BITSHUFFLE
+using .bitshuffle_jll_ext: BSHUF_H5_COMPRESS_LZ4
+using .bitshuffle_jll_ext: BSHUF_H5_COMPRESS_ZSTD
+using .bitshuffle_jll_ext: H5Z_FILTER_BITSHUFFLE
 
-const BSHUF_VERSION_MAJOR = bitshuffle_jll_ext.BSHUF_VERSION_MAJOR
-const BSHUF_VERSION_MINOR = bitshuffle_jll_ext.BSHUF_VERSION_MINOR
-const BSHUF_VERSION_POINT = bitshuffle_jll_ext.BSHUF_VERSION_POINT
+using .bitshuffle_jll_ext: BSHUF_VERSION_MAJOR
+using .bitshuffle_jll_ext: BSHUF_VERSION_MINOR
+using .bitshuffle_jll_ext: BSHUF_VERSION_POINT
 
-const bitshuffle_name = bitshuffle_jll_ext.bitshuffle_name
+using .bitshuffle_jll_ext: bitshuffle_name
 
 end # module
diff --git a/filters/H5Zblosc/src/H5Zblosc.jl b/filters/H5Zblosc/src/H5Zblosc.jl
@@ -3,6 +3,8 @@ module H5Zblosc
 
 import Blosc
 using HDF5: HDF5
+
+# The next block of lines can be removed
 using HDF5.API
 import HDF5.Filters: Filter, FilterPipeline
 import HDF5.Filters:
@@ -22,11 +24,11 @@ import Blosc: NOSHUFFLE, SHUFFLE, BITSHUFFLE
 
 const BloscExt = Base.get_extension(HDF5, :BloscExt)
 
-const blosc_filter = BloscExt.blosc_filter
-const BloscFilter = BloscExt.BloscFilter
+using .BloscExt: blosc_filter
+using .BloscExt: BloscFilter
 
-const H5Z_FILTER_BLOSC = BloscExt.H5Z_FILTER_BLOSC
-const FILTER_BLOSC_VERSION = BloscExt.FILTER_BLOSC_VERSION
-const blosc_name = BloscExt.blosc_name
+using .BloscExt: H5Z_FILTER_BLOSC
+using .BloscExt: FILTER_BLOSC_VERSION
+using .BloscExt: blosc_name
 
 end # module H5Zblosc
diff --git a/filters/H5Zbzip2/src/H5Zbzip2.jl b/filters/H5Zbzip2/src/H5Zbzip2.jl
@@ -6,6 +6,7 @@ module H5Zbzip2
 using CodecBzip2: libbzip2
 using HDF5: HDF5
 
+# Remove the next three lines in the future
 using HDF5.API
 import HDF5.Filters:
     Filter, filterid, register_filter, filtername, filter_func, filter_cfunc
@@ -14,9 +15,9 @@ export H5Z_FILTER_BZIP2, H5Z_filter_bzip2, Bzip2Filter
 
 const CodecBzip2Ext = Base.get_extension(HDF5, :CodecBzip2Ext)
 
-const H5Z_FILTER_BZIP2 = CodecBzip2Ext.H5Z_FILTER_BZIP2
-const H5Z_filter_bzip2 = CodecBzip2Ext.H5Z_filter_bzip2
-const Bzip2Filter = CodecBzip2Ext.Bzip2Filter
-const bzip2_name = CodecBzip2Ext.bzip2_name
-                      
+using .CodecBzip2Ext: H5Z_FILTER_BZIP2
+using .CodecBzip2Ext: H5Z_filter_bzip2
+using .CodecBzip2Ext: Bzip2Filter
+using .CodecBzip2Ext: bzip2_name
+
 end # module H5Zbzip2
diff --git a/filters/H5Zlz4/src/H5Zlz4.jl b/filters/H5Zlz4/src/H5Zlz4.jl
@@ -5,6 +5,8 @@ module H5Zlz4
 
 using CodecLz4
 using HDF5: HDF5
+
+# The next three lines can be removed
 using HDF5.API
 import HDF5.Filters:
     Filter, filterid, register_filter, filtername, filter_func, filter_cfunc
@@ -13,14 +15,14 @@ export H5Z_FILTER_LZ4, H5Z_filter_lz4, Lz4Filter
 
 const CodecLz4Ext = Base.get_extension(HDF5, :CodecLz4Ext)
 
-const H5Z_filter_lz4 = CodecLz4Ext.H5Z_filter_lz4
-const Lz4Filter = CodecLz4Ext.Lz4Filter
+using .CodecLz4Ext: H5Z_filter_lz4
+using .CodecLz4Ext: Lz4Filter
 
-const H5Z_FILTER_LZ4 = CodecLz4Ext.H5Z_FILTER_LZ4
+using .CodecLz4Ext: H5Z_FILTER_LZ4
 
-const DEFAULT_BLOCK_SIZE = CodecLz4Ext.DEFAULT_BLOCK_SIZE
-const lz4_name = CodecLz4Ext.lz4_name
+using .CodecLz4Ext: DEFAULT_BLOCK_SIZE
+using .CodecLz4Ext: lz4_name
 
-const LZ4_AGGRESSION = CodecLz4Ext.LZ4_AGGRESSION
+using .CodecLz4Ext: LZ4_AGGRESSION
 
 end
diff --git a/filters/H5Zzstd/src/H5Zzstd.jl b/filters/H5Zzstd/src/H5Zzstd.jl
@@ -12,12 +12,12 @@ using HDF5: HDF5
 using CodecZstd: CodecZstd
 const CodecZstdExt = Base.get_extension(HDF5, :CodecZstdExt)
 
-const H5Z_FILTER_ZSTD = CodecZstdExt.H5Z_FILTER_ZSTD
-const zstd_name = CodecZstdExt.zstd_name
+using .CodecZstdExt: H5Z_FILTER_ZSTD
+using .CodecZstdExt: zstd_name
 
-const H5Z_filter_zstd = CodecZstdExt.H5Z_filter_zstd
-const H5Z_FILTER_ZSTD = CodecZstdExt.H5Z_FILTER_ZSTD
-const ZstdFilter = CodecZstdExt.ZstdFilter
+using .CodecZstdExt: H5Z_filter_zstd
+using .CodecZstdExt: H5Z_FILTER_ZSTD
+using .CodecZstdExt: ZstdFilter
 
 export H5Z_filter_zstd, H5Z_FILTER_ZSTD, ZstdFilter