Add filters documentation (JuliaIO#901)

* Add filters documentation

* Fix typo

* Rearrange filters.md

* Add named header id tags for API

* Add create_dataset documentation

* Cross ref dataset properties

Author: mkitti

docs/Project.toml

@@ -1,4 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+H5Zblosc = "c8ec2601-a99c-407f-b158-e79c03c2f5f7"
+H5Zbzip2 = "094576f2-1e46-4c84-8e32-c46c042eaaa2"
+H5Zlz4 = "eb20ec05-5464-47b5-ba41-098e3c1068a3"
+H5Zzstd = "f6f2d980-1ec6-471c-a70d-0270e22f1103"
 HDF5 = "f67ccb44-e63f-5c2f-98bd-6dc0ccc4ba2f"
 MPI = "da04e1cc-30fd-572f-bb4f-1f8673147195"

docs/make.jl

@@ -1,5 +1,9 @@
 using Documenter
 using HDF5
+using H5Zblosc
+using H5Zbzip2
+using H5Zlz4
+using H5Zzstd
 using MPI  # needed to generate docs for parallel HDF5 API
 
 # Used in index.md to filter the autodocs list
@@ -17,7 +21,7 @@ not_low_level_api(::typeof(HDF5.API.h5t_get_tag)) = false
 
 makedocs(;
     sitename="HDF5.jl",
-    modules=[HDF5],
+    modules=[HDF5, H5Zblosc, H5Zbzip2, H5Zlz4, H5Zzstd],
     authors="Mustafa Mohamad <mus-m@outlook.com> and contributors",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
@@ -28,7 +32,9 @@ makedocs(;
     pages=[
         "Home" => "index.md",
         "Interface" => [
+            "dataset.md",
             "properties.md",
+            "filters.md"
         ],
         "Low-level library bindings" => "api_bindings.md",
     ],

docs/src/api_bindings.md

@@ -22,7 +22,7 @@ documented here.
 
 ---
 
-## [`H5`](https://portal.hdfgroup.org/display/HDF5/Library) — General Library Functions
+## [[`H5`](https://portal.hdfgroup.org/display/HDF5/Library) — General Library Functions](@id H5)
 - [`h5_close`](@ref h5_close)
 - [`h5_dont_atexit`](@ref h5_dont_atexit)
 - [`h5_free_memory`](@ref h5_free_memory)
@@ -44,7 +44,7 @@ h5_set_free_list_limits
 
 ---
 
-## [`H5A`](https://portal.hdfgroup.org/display/HDF5/Attributes) — Attribute Interface
+## [[`H5A`](https://portal.hdfgroup.org/display/HDF5/Attributes) — Attribute Interface](@id H5A)
 - [`h5a_close`](@ref h5a_close)
 - [`h5a_create`](@ref h5a_create)
 - [`h5a_create_by_name`](@ref h5a_create_by_name)
@@ -84,7 +84,7 @@ h5a_write
 
 ---
 
-## [`H5D`](https://portal.hdfgroup.org/display/HDF5/Datasets) — Dataset Interface
+## [[`H5D`](https://portal.hdfgroup.org/display/HDF5/Datasets) — Dataset Interface](@id H5D)
 - [`h5d_close`](@ref h5d_close)
 - [`h5d_create`](@ref h5d_create)
 - [`h5d_extend`](@ref h5d_extend)
@@ -146,7 +146,7 @@ h5d_write_chunk
 
 ---
 
-## [`H5E`](https://portal.hdfgroup.org/display/HDF5/Error+Handling) — Error Interface
+## [[`H5E`](https://portal.hdfgroup.org/display/HDF5/Error+Handling) — Error Interface](@id H5E)
 - [`h5e_close_stack`](@ref h5e_close_stack)
 - [`h5e_get_auto`](@ref h5e_get_auto)
 - [`h5e_get_current_stack`](@ref h5e_get_current_stack)
@@ -166,7 +166,7 @@ h5e_walk
 
 ---
 
-## [`H5F`](https://portal.hdfgroup.org/display/HDF5/Files) — File Interface
+## [[`H5F`](https://portal.hdfgroup.org/display/HDF5/Files) — File Interface](@id H5F)
 - [`h5f_close`](@ref h5f_close)
 - [`h5f_create`](@ref h5f_create)
 - [`h5f_flush`](@ref h5f_flush)
@@ -198,7 +198,7 @@ h5f_start_swmr_write
 
 ---
 
-## [`H5G`](https://portal.hdfgroup.org/display/HDF5/Groups) — Group Interface
+## [[`H5G`](https://portal.hdfgroup.org/display/HDF5/Groups) — Group Interface](@id H5G)
 - [`h5g_close`](@ref h5g_close)
 - [`h5g_create`](@ref h5g_create)
 - [`h5g_get_create_plist`](@ref h5g_get_create_plist)
@@ -218,7 +218,7 @@ h5g_open
 
 ---
 
-## [`H5I`](https://portal.hdfgroup.org/display/HDF5/Identifiers) — Identifier Interface
+## [[`H5I`](https://portal.hdfgroup.org/display/HDF5/Identifiers) — Identifier Interface](@id H5I)
 - [`h5i_dec_ref`](@ref h5i_dec_ref)
 - [`h5i_get_file_id`](@ref h5i_get_file_id)
 - [`h5i_get_name`](@ref h5i_get_name)
@@ -238,7 +238,7 @@ h5i_is_valid
 
 ---
 
-## [`H5L`](https://portal.hdfgroup.org/display/HDF5/Links) — Link Interface
+## [[`H5L`](https://portal.hdfgroup.org/display/HDF5/Links) — Link Interface](@id H5L)
 - [`h5l_create_external`](@ref h5l_create_external)
 - [`h5l_create_hard`](@ref h5l_create_hard)
 - [`h5l_create_soft`](@ref h5l_create_soft)
@@ -262,7 +262,7 @@ h5l_move
 
 ---
 
-## [`H5O`](https://portal.hdfgroup.org/display/HDF5/Objects) — Object Interface
+## [[`H5O`](https://portal.hdfgroup.org/display/HDF5/Objects) — Object Interface](@id H5O)
 - [`h5o_close`](@ref h5o_close)
 - [`h5o_copy`](@ref h5o_copy)
 - [`h5o_get_info`](@ref h5o_get_info)
@@ -280,7 +280,7 @@ h5o_open_by_idx
 
 ---
 
-## [`H5P`](https://portal.hdfgroup.org/display/HDF5/Property+Lists) — Property Interface
+## [[`H5P`](https://portal.hdfgroup.org/display/HDF5/Property+Lists) — Property Interface](@id H5P)
 - [`h5p_close`](@ref h5p_close)
 - [`h5p_create`](@ref h5p_create)
 - [`h5p_get_alignment`](@ref h5p_get_alignment)
@@ -384,7 +384,7 @@ h5p_set_virtual
 
 ---
 
-## [`H5R`](https://portal.hdfgroup.org/display/HDF5/References) — Reference Interface
+## [[`H5R`](https://portal.hdfgroup.org/display/HDF5/References) — Reference Interface](@id H5R)
 - [`h5r_create`](@ref h5r_create)
 - [`h5r_dereference`](@ref h5r_dereference)
 - [`h5r_get_obj_type`](@ref h5r_get_obj_type)
@@ -398,7 +398,7 @@ h5r_get_region
 
 ---
 
-## [`H5S`](https://portal.hdfgroup.org/display/HDF5/Dataspaces) — Dataspace Interface
+## [[`H5S`](https://portal.hdfgroup.org/display/HDF5/Dataspaces) — Dataspace Interface](@id H5S)
 - [`h5s_close`](@ref h5s_close)
 - [`h5s_combine_select`](@ref h5s_combine_select)
 - [`h5s_copy`](@ref h5s_copy)
@@ -438,7 +438,7 @@ h5s_set_extent_simple
 
 ---
 
-## [`H5T`](https://portal.hdfgroup.org/display/HDF5/Datatypes) — Datatype Interface
+## [[`H5T`](https://portal.hdfgroup.org/display/HDF5/Datatypes) — Datatype Interface](@id H5T)
 - [`h5t_array_create`](@ref h5t_array_create)
 - [`h5t_close`](@ref h5t_close)
 - [`h5t_commit`](@ref h5t_commit)
@@ -520,15 +520,15 @@ h5t_vlen_create
 
 ---
 
-## [`H5Z`](https://portal.hdfgroup.org/display/HDF5/Filters) — Filter Interface
+## [[`H5Z`](https://portal.hdfgroup.org/display/HDF5/Filters) — Filter Interface](@id H5Z)
 - [`h5z_register`](@ref h5z_register)
 ```@docs
 h5z_register
 ```
 
 ---
 
-## [`H5DO`](https://portal.hdfgroup.org/display/HDF5/Optimizations) — Optimized Functions Interface
+## [[`H5DO`](https://portal.hdfgroup.org/display/HDF5/Optimizations) — Optimized Functions Interface](@id H5DO)
 - [`h5do_append`](@ref h5do_append)
 - [`h5do_write_chunk`](@ref h5do_write_chunk)
 ```@docs
@@ -538,7 +538,7 @@ h5do_write_chunk
 
 ---
 
-## [`H5DS`](https://portal.hdfgroup.org/display/HDF5/Dimension+Scales) — Dimension Scale Interface
+## [[`H5DS`](https://portal.hdfgroup.org/display/HDF5/Dimension+Scales) — Dimension Scale Interface](@id H5DS)
 - [`h5ds_attach_scale`](@ref h5ds_attach_scale)
 - [`h5ds_detach_scale`](@ref h5ds_detach_scale)
 - [`h5ds_get_label`](@ref h5ds_get_label)
@@ -562,15 +562,15 @@ h5ds_set_scale
 
 ---
 
-## [`H5LT`](https://portal.hdfgroup.org/display/HDF5/Lite) — Lite Interface
+## [[`H5LT`](https://portal.hdfgroup.org/display/HDF5/Lite) — Lite Interface](@id H5LT)
 - [`h5lt_dtype_to_text`](@ref h5lt_dtype_to_text)
 ```@docs
 h5lt_dtype_to_text
 ```
 
 ---
 
-## [`H5TB`](https://portal.hdfgroup.org/display/HDF5/Tables) — Table Interface
+## [[`H5TB`](https://portal.hdfgroup.org/display/HDF5/Tables) — Table Interface](@id H5TB)
 - [`h5tb_append_records`](@ref h5tb_append_records)
 - [`h5tb_get_field_info`](@ref h5tb_get_field_info)
 - [`h5tb_get_table_info`](@ref h5tb_get_table_info)

docs/src/dataset.md

@@ -0,0 +1,7 @@
+# Dataset
+
+Many dataset operations are available through the indexing interface, which is aliased to the functional interface. Below describes the functional interface.
+
+```@docs
+create_dataset
+```

docs/src/filters.md

@@ -0,0 +1,122 @@
+# Filters
+
+HDF5 supports filters for compression and validation: these are applied sequentially to
+each chunk of a dataset when writing data, and in reverse order when reading data.
+
+```@meta
+CurrentModule = HDF5
+```
+
+These can be set by passing a filter or vector of filters as a `filters` property to
+[`DatasetCreateProperties`](@ref) or via the `filters` keyword argument of [`create_dataset`](@ref).
+
+```@meta
+CurrentModule = HDF5.Filters
+```
+
+## Example
+
+```@docs
+Filters
+```
+
+## Built-in Filters
+
+
+```@docs
+Deflate
+Shuffle
+Fletcher32
+Szip
+NBit
+ScaleOffset
+UnknownFilter
+```
+
+## External Filter Packages
+
+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
+[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.
+
+### H5Zblosc.jl
+
+```@meta
+CurrentModule = H5Zblosc
+```
+
+```@docs
+BloscFilter
+```
+
+### H5Zbzip2.jl
+
+```@meta
+CurrentModule = H5Zbzip2
+```
+
+```@docs
+Bzip2Filter
+```
+
+### H5Zlz4.jl
+
+```@meta
+CurrentModule = H5Zlz4
+```
+
+```@docs
+Lz4Filter
+```
+
+### H5Zzstd.jl
+
+```@meta
+CurrentModule = H5Zzstd
+```
+
+```@docs
+ZstdFilter
+```
+
+## Other External Filters
+
+Additional filters can be dynamically loaded by the HDF5 library. See [External Links](@ref) below for more information.
+
+## Filter Interface
+
+```@meta
+CurrentModule = HDF5.Filters
+```
+
+The filter interface is used to describe filters and obtain information on them.
+
+```@docs
+Filter
+FilterPipeline
+FILTERS
+filterid
+encoder_present
+decoder_present
+filtername
+can_apply_func
+can_apply_cfunc
+set_local_func
+set_local_cfunc
+filter_func
+filter_cfunc
+register_filter
+```
+
+## External Links
+
+* A [list of registered filter plugins](https://portal.hdfgroup.org/display/support/Registered+Filter+Plugins) can be found on the HDF Group website.
+* [See the HDF5 Documentation of HDF5 Filter Plugins for details.](https://portal.hdfgroup.org/display/support/HDF5+Filter+Plugins)
+* The source code for many external plugins have been collected in the [HDFGroup hdf5_plugins repository](https://github.com/HDFGroup/hdf5_plugins).
+* [Compiled binaries of dynamically downloaded plugins](https://portal.hdfgroup.org/display/support/Downloads) by downloaded from HDF5 Group.

docs/src/properties.md

@@ -21,32 +21,12 @@ FileAccessProperties
 FileCreateProperties
 GroupCreateProperties
 DatasetCreateProperties
+DatasetAccessProperties
 DatasetTransferProperties
 LinkCreateProperties
 ObjectCreateProperties
-```
-
-## Filters
-
-HDF5 supports filters for compression and validation: these are applied sequentially to
-each chunk of a dataset when writing data, and in reverse order when reading data.
-
-These can be set by passing a filter or vector of filters as a `filter` property to
-[`DatasetCreateProperties`](@ref).
-
-```@meta
-CurrentModule = HDF5.Filters
-```
-
-```@docs
-FilterPipeline
-Deflate
-Shuffle
-Fletcher32
-Szip
-NBit
-ScaleOffset
-BloscFilter
+StringCreateProperties
+DatatypeCreateProperties
 ```
 
 ## Drivers

filters/H5Zblosc/README.md

@@ -0,0 +1,6 @@
+# H5Zblosc.jl
+
+Implements the Blosc filter for [HDF5.jl](https://github.com/JuliaIO/HDF5.jl) in Julia.
+See the [documentation](https://juliaio.github.io/HDF5.jl/stable/filters/#H5Zblosc.jl)
+
+This implements [HDF5 filter ID 32001](https://portal.hdfgroup.org/display/support/Filters#Filters-32001)

filters/H5Zblosc/src/H5Zblosc.jl

@@ -5,6 +5,7 @@ import Blosc
 using HDF5.API
 import HDF5.Filters: Filter, FilterPipeline
 import HDF5.Filters: filterid, register_filter, filtername, filter_func, filter_cfunc, set_local_func, set_local_cfunc
+import HDF5.Filters.Shuffle
 
 export H5Z_FILTER_BLOSC, blosc_filter, BloscFilter
 
@@ -124,7 +125,9 @@ The Blosc compression filter, using [Blosc.jl](https://github.com/JuliaIO/Blosc.
  - `compressor`: the compression algorithm. Call `Blosc.compressors()` for the available compressors.
 
 # External links
-- [What Is Blosc?](https://www.blosc.org/pages/blosc-in-depth/)
+* [What Is Blosc?](https://www.blosc.org/pages/blosc-in-depth/)
+* [Blosc HDF5 Filter ID 32001](https://portal.hdfgroup.org/display/support/Filters#Filters-32001)
+* [Blosc HDF5 Plugin Repository (C code)](https://github.com/Blosc/hdf5-blosc)
 """
 struct BloscFilter <: Filter
     blosc_version::Cuint