diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 3b10bac87..c97bf41c5 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -127,13 +127,3 @@ jobs: @info "Not compatible with this release. No problem." exception=err exit(0) # Exit immediately, as a success end - - docs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: julia-actions/julia-buildpkg@latest - - uses: julia-actions/julia-docdeploy@latest - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} diff --git a/.github/workflows/Docs.yml b/.github/workflows/Docs.yml new file mode 100644 index 000000000..d8028c278 --- /dev/null +++ b/.github/workflows/Docs.yml @@ -0,0 +1,18 @@ +name: Documenter +on: + push: + branches: [master] + tags: [v*] + pull_request: + +jobs: + + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: julia-actions/julia-buildpkg@latest + - uses: julia-actions/julia-docdeploy@latest + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} diff --git a/docs/make.jl b/docs/make.jl index 0c024ea45..b9b5cfced 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -29,9 +29,12 @@ makedocs(; assets=String[], sidebar_sitename=false ), + strict=true, pages=[ "Home" => "index.md", "Interface" => [ + "interface/configuration.md", + "interface/files.md", "interface/groups.md", "interface/dataspaces.md", "interface/dataset.md", diff --git a/docs/src/api_bindings.md b/docs/src/api_bindings.md index 0aa7b6cdf..2a6a5f000 100644 --- a/docs/src/api_bindings.md +++ b/docs/src/api_bindings.md @@ -344,6 +344,7 @@ h5l_move - [`h5o_get_comment`](@ref h5o_get_comment) - [`h5o_get_comment_by_name`](@ref h5o_get_comment_by_name) - [`h5o_get_info`](@ref h5o_get_info) +- [`h5o_get_info1`](@ref h5o_get_info1) - [`h5o_get_info_by_idx`](@ref h5o_get_info_by_idx) - [`h5o_get_info_by_name`](@ref h5o_get_info_by_name) - [`h5o_get_native_info`](@ref h5o_get_native_info) @@ -374,6 +375,7 @@ h5o_flush h5o_get_comment h5o_get_comment_by_name h5o_get_info +h5o_get_info1 h5o_get_info_by_idx h5o_get_info_by_name h5o_get_native_info @@ -1016,6 +1018,26 @@ h5z_unregister --- +## [[`H5FD`](https://portal.hdfgroup.org/display/HDF5/File+Drivers) — File Drivers](@id H5FD) +- [`h5fd_core_init`](@ref h5fd_core_init) +- [`h5fd_family_init`](@ref h5fd_family_init) +- [`h5fd_log_init`](@ref h5fd_log_init) +- [`h5fd_mpio_init`](@ref h5fd_mpio_init) +- [`h5fd_multi_init`](@ref h5fd_multi_init) +- [`h5fd_sec2_init`](@ref h5fd_sec2_init) +- [`h5fd_stdio_init`](@ref h5fd_stdio_init) +```@docs +h5fd_core_init +h5fd_family_init +h5fd_log_init +h5fd_mpio_init +h5fd_multi_init +h5fd_sec2_init +h5fd_stdio_init +``` + +--- + ## [[`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) diff --git a/docs/src/index.md b/docs/src/index.md index 16462c509..591382404 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -536,16 +536,3 @@ Note that some languages or libraries use both methods, so please check the dats improving the handling of HDF5's constants - Thanks also to the users who have reported bugs and tested fixes - -# API Reference - -Below we include a limited number of API references. Note not all of these are public interfaces, thus proceed with caution. - -```@index -Pages = ["index.md"] -``` - -```@autodocs -Modules = [HDF5] -Filter = not_low_level_api -``` diff --git a/docs/src/interface/attributes.md b/docs/src/interface/attributes.md index 3277daead..7f01f0965 100644 --- a/docs/src/interface/attributes.md +++ b/docs/src/interface/attributes.md @@ -1,5 +1,9 @@ # Attributes +```@meta +CurrentModule = HDF5 +``` + ## Dictionary interface ```@docs @@ -10,7 +14,7 @@ attributes ## Mid-level Interface ```@docs -HDF5.Attribute +Attribute open_attribute create_attribute read_attribute @@ -24,4 +28,5 @@ rename_attribute ```@docs h5readattr h5writeattr -``` \ No newline at end of file +num_attrs +``` diff --git a/docs/src/interface/configuration.md b/docs/src/interface/configuration.md new file mode 100644 index 000000000..f6156cc88 --- /dev/null +++ b/docs/src/interface/configuration.md @@ -0,0 +1,26 @@ +# Configuration + +```@meta +CurrentModule = HDF5 +``` + +```@docs +has_parallel +has_ros3 +``` + +## Display + +```@docs +SHOW_TREE_ICONS +SHOW_TREE_MAX_CHILDREN +SHOW_TREE_MAX_DEPTH +``` + +## Internals + +```@docs +get_context_property +CONTEXT +HDF5Context +``` \ No newline at end of file diff --git a/docs/src/interface/dataset.md b/docs/src/interface/dataset.md index b492c2fdd..c488dcbf7 100644 --- a/docs/src/interface/dataset.md +++ b/docs/src/interface/dataset.md @@ -1,7 +1,29 @@ # Dataset +```@meta +CurrentModule = HDF5 +``` + Many dataset operations are available through the indexing interface, which is aliased to the functional interface. Below describes the functional interface. ```@docs create_dataset +Base.copyto! +Base.similar +create_external_dataset +get_datasets +``` + +## Chunks + +```@docs +do_read_chunk +do_write_chunk +get_chunk_index +get_chunk_length +get_chunk_offset +get_num_chunks +get_num_chunks_per_dim +read_chunk +write_chunk ``` \ No newline at end of file diff --git a/docs/src/interface/dataspaces.md b/docs/src/interface/dataspaces.md index fed9cdf9b..e1c0db2f1 100644 --- a/docs/src/interface/dataspaces.md +++ b/docs/src/interface/dataspaces.md @@ -1,10 +1,21 @@ # Dataspaces +```@meta +CurrentModule = HDF5 +``` + ```@docs -HDF5.Dataspace +Dataspace dataspace -HDF5.isnull -HDF5.BlockRange -HDF5.select_hyperslab! -HDF5.get_regular_hyperslab +isnull +get_extent_dims +set_extent_dims ``` + +# Hyperslab + +```@docs +BlockRange +select_hyperslab! +get_regular_hyperslab +``` \ No newline at end of file diff --git a/docs/src/interface/files.md b/docs/src/interface/files.md new file mode 100644 index 000000000..74918d6df --- /dev/null +++ b/docs/src/interface/files.md @@ -0,0 +1,12 @@ +# Files + +```@meta +CurrentModule = HDF5 +``` + +```@docs +h5open +ishdf5 +Base.isopen +start_swmr_write +``` diff --git a/docs/src/interface/filters.md b/docs/src/interface/filters.md index a6026a6ac..88af03692 100644 --- a/docs/src/interface/filters.md +++ b/docs/src/interface/filters.md @@ -172,10 +172,16 @@ The filter interface is used to describe filters and obtain information on them. ```@docs Filter FilterPipeline +UnknownFilter FILTERS +EXTERNAL_FILTER_JULIA_PACKAGES filterid -encoder_present +isavailable +isdecoderenabled +isencoderenabled decoder_present +encoder_present +ensure_filters_available filtername can_apply_func can_apply_cfunc diff --git a/docs/src/interface/groups.md b/docs/src/interface/groups.md index 3c1af4878..31b069b8a 100644 --- a/docs/src/interface/groups.md +++ b/docs/src/interface/groups.md @@ -1,6 +1,12 @@ # Groups +```@meta +CurrentModule = HDF5 +``` + ```@docs -HDF5.create_group -HDF5.open_group +Group +create_group +open_group +create_external ``` diff --git a/docs/src/interface/properties.md b/docs/src/interface/properties.md index 4a22ccdd1..20715c276 100644 --- a/docs/src/interface/properties.md +++ b/docs/src/interface/properties.md @@ -13,6 +13,12 @@ so users will not usually be required to construct them manually. Not all properties defined by the HDF5 library are currently available in HDF5.jl. If you require additional properties, please open an issue or pull request. +## Common functions + +```@docs +setproperties! +``` + ## `Properties` types ```@docs @@ -33,7 +39,7 @@ DatatypeCreateProperties ```@docs VirtualMapping -VirtualLyout +VirtualLayout ``` ## Drivers @@ -55,3 +61,17 @@ ROS3 MPIO ``` +## Internals + +```@meta +CurrentModule = HDF5 +``` + +The following macros are used for defining new properties and property getters/setters. + +```@docs +@propertyclass +@bool_property +@enum_property +@tuple_property +``` \ No newline at end of file diff --git a/gen/gen_wrappers.jl b/gen/gen_wrappers.jl index 91738b058..3014593b4 100644 --- a/gen/gen_wrappers.jl +++ b/gen/gen_wrappers.jl @@ -15,6 +15,10 @@ Base.remove_linenums!(exprs) # Definitions which are not automatically generated, but should still be documented as # part of the raw low-level API: +append!(bound_api["H5O"], [ + # defined in src/api/helpers.jl + "h5o_get_info1", +]) append!(bound_api["H5P"], [ # defined in src/api/helpers.jl "h5p_get_class_name", @@ -105,6 +109,7 @@ for (mod, desc, urltail) in ( ("H5S", "Dataspace Interface", "Dataspaces"), ("H5T", "Datatype Interface", "Datatypes"), ("H5Z", "Filter Interface", "Filters"), + ("H5FD", "File Drivers", "File+Drivers"), ("H5DO", "Optimized Functions Interface", "Optimizations"), ("H5DS", "Dimension Scale Interface", "Dimension+Scales"), ("H5LT", "Lite Interface", "Lite"), diff --git a/src/HDF5.jl b/src/HDF5.jl index 677725712..54c995741 100644 --- a/src/HDF5.jl +++ b/src/HDF5.jl @@ -92,10 +92,9 @@ const HAS_ROS3 = Ref(false) """ has_parallel() -Returns `true` if the HDF5 libraries were compiled with parallel support, -and if parallel functionality was loaded into HDF5.jl. +Returns `true` if the HDF5 libraries were compiled with MPI parallel support via the [`Drivers.MPIO`](@ref) driver. -For the second condition to be true, MPI.jl must be imported before HDF5.jl. +See [Parallel HDF5](@ref) for more details. """ has_parallel() = HAS_PARALLEL[] diff --git a/src/datasets.jl b/src/datasets.jl index 724f3f5e1..631a02430 100644 --- a/src/datasets.jl +++ b/src/datasets.jl @@ -36,8 +36,6 @@ Additionally, the initial create, transfer, and access properties can be provide * `dxpl` - [`DatasetTransferProperties`](@ref) * `dapl` - [`DatasetAccessProperties`](@ref) -See also -* [`H5P`](@ref H5P) """ function create_dataset( parent::Union{File,Group}, @@ -366,16 +364,14 @@ end """ create_external_dataset(parent, name, filepath, dtype, dspace, offset = 0) -Create a external dataset with data in an external file. +Create an external dataset with data in an external file. * `parent` - File or Group * `name` - Name of the Dataset * `filepath` - File path to where the data is tored * `dtype` - Datatype, Type, or value where `datatype` is applicable * `offset` - Offset, in bytes, from the beginning of the file to the location in the file where the data starts. -Use `API.h5p_set_external` to link to multiple segments. - -See also [`API.h5p_set_external`](@ref) +See also [`API.h5p_set_external`](@ref) to link to multiple segments. """ function create_external_dataset( parent::Union{File,Group}, diff --git a/src/dataspaces.jl b/src/dataspaces.jl index f5040a184..cea2773ee 100644 --- a/src/dataspaces.jl +++ b/src/dataspaces.jl @@ -161,7 +161,8 @@ selecting multiple contiguous blocks. - `count`: the number of blocks (can be -1 for an unlimited number of blocks) - `block`: the number of elements in each block. - BlockRange(obj::Union{Integer, OrdinalRange}) + + HDF5.BlockRange(obj::Union{Integer, OrdinalRange}) Convert `obj` to a `BlockRange` object. @@ -202,7 +203,7 @@ Base.convert(::Type{T}, br::BlockRange) where {T<:AbstractRange} = convert(T, ra HDF5.select_hyperslab!(dspace::Dataspace, [op, ], idxs::Tuple) Selects a hyperslab region of the `dspace`. `idxs` should be a tuple of -integers, ranges or [`blockrange`](@ref) objects. +integers, ranges or [`BlockRange`](@ref) objects. - `op` determines how the new selection is to be combined with the already selected dataspace: diff --git a/src/drivers/mpio.jl b/src/drivers/mpio.jl index 347af743e..ea39d5f57 100644 --- a/src/drivers/mpio.jl +++ b/src/drivers/mpio.jl @@ -1,5 +1,6 @@ using .MPI import Libdl +import HDF5: h5open ### ### MPIO @@ -53,6 +54,11 @@ built with MPI support. - `comm` is the communicator over which the file will be opened. - `info`/`kwargs` are MPI-IO options, and are passed to `MPI_FILE_OPEN`. +# See also + +- [`HDF5.has_parallel`](@ref) +- [Parallel HDF5](@ref) + # External links - $(h5doc("H5P_SET_FAPL_MPIO")) @@ -96,15 +102,15 @@ support. See the [HDF5 docs](https://portal.hdfgroup.org/display/HDF5/H5P_SET_FAPL_MPIO) for details on the `comm` and `info` arguments. """ -function HDF5.h5open( +function h5open( filename::AbstractString, mode::AbstractString, comm::MPI.Comm, info::MPI.Info=MPI.Info(); pv... ) - HDF5.h5open(filename, mode; driver=MPIO(comm, info), pv...) + h5open(filename, mode; driver=MPIO(comm, info), pv...) end -HDF5.h5open(filename::AbstractString, comm::MPI.Comm, args...; pv...) = - HDF5.h5open(filename, "r", comm, args...; pv...) +h5open(filename::AbstractString, comm::MPI.Comm, args...; pv...) = + h5open(filename, "r", comm, args...; pv...) diff --git a/src/file.jl b/src/file.jl index c2f3afa9d..d8c151b53 100644 --- a/src/file.jl +++ b/src/file.jl @@ -160,7 +160,9 @@ filename(obj::Union{File,Group,Dataset,Attribute,Datatype}) = start_swmr_write(h5::HDF5.File) Start Single Reader Multiple Writer (SWMR) writing mode. -See [SWMR documentation](https://portal.hdfgroup.org/display/HDF5/Single+Writer+Multiple+Reader++-+SWMR). + +# External links +[*Single Writer Multiple Reader* from the HDF5 manual](https://portal.hdfgroup.org/display/HDF5/Single+Writer+Multiple+Reader++-+SWMR). """ start_swmr_write(h5::File) = API.h5f_start_swmr_write(h5) diff --git a/src/groups.jl b/src/groups.jl index 83621c74f..133baa502 100644 --- a/src/groups.jl +++ b/src/groups.jl @@ -174,7 +174,10 @@ move_link( lcpl_id=HDF5.API.H5P_DEFAULT, lapl_id=HDF5.H5P.DEFAULT) Create an external link such that `source[source_relpath]` points to `target_path` within the file -with path `target_filename`; Calls `[H5Lcreate_external](https://www.hdfgroup.org/HDF5/doc/RM/RM_H5L.html#Link-CreateExternal)`. +with path `target_filename`. + +# See also +[`API.h5l_create_external`](@ref) """ function create_external( source::Union{File,Group}, diff --git a/src/properties.jl b/src/properties.jl index bc9b6c5b4..1ca0033fa 100644 --- a/src/properties.jl +++ b/src/properties.jl @@ -843,7 +843,7 @@ superclass(::Type{AttributeAccessProperties}) = LinkAccessProperties Properties used when transferring data to/from datasets -- `dxpl_mpio`: MPI transfer mode: +- `dxpl_mpio`: MPI transfer mode when using [`Drivers.MPIO`](@ref) file driver: - `:independent`: use independent I/O access (default), - `:collective`: use collective I/O access.