some fixes for docs (#1042)

* fix links * makedocs strict * clean up docs
JuliaIO · Jan 23, 2023 · 9a90e4e · 9a90e4e
1 parent 0ee01fe
commit 9a90e4e
Show file tree

Hide file tree

Showing 21 changed files with 192 additions and 52 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
-```
+num_attrs
+```
diff --git a/docs/src/interface/configuration.md 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
+```
diff --git 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
 ```
diff --git 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
+```
diff --git a/docs/src/interface/files.md 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
@@ -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
@@ -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
@@ -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
+```
diff --git 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
@@ -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
@@ -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
@@ -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: