The portal.hdgroup.org URLs have a nice feature in that they encode the name of the function n the URL:https://portal.hdfgroup.org/display/HDF5/H5D_CLOSE
The new docs.hdfgroup.org URLs use numbered “title” anchors.https://docs.hdfgroup.org/hdf5/develop/group___h5_d.html#title7
I would be nice if the new docs had predictable anchors for the function names. For example, it would great if the following worked.https://docs.hdfgroup.org/hdf5/develop/group___h5_d.html#H5D_CLOSE
In the Julia language package HDF5.jl, we generate our documentation with links to the online HDF5 documentation because of the predictability of the URLs. It would be sad to lose this if the old documentation were to go away.https://juliaio.github.io/HDF5.jl/stable/api_bindings/#HDF5.API.h5d_close
end
if prefix == "h5fd" && endswith(rest, "_init")
# remove trailing _init
drivername = rest[1:end-5]
docstr *= "\n\nThis function is exposed in `libhdf5` as the macro `H5FD_$(uppercase(drivername))`. " *
"See `libhdf5` documentation for [`H5Pget_driver`]" *
"(https://portal.hdfgroup.org/display/HDF5/H5P_GET_DRIVER).\n"
else
docstr *= "\n\nSee `libhdf5` documentation for [`$cfuncname`]" *
"(https://portal.hdfgroup.org/display/HDF5/$(uppercase(string(funcsig.args[1])))).\n"
end
# Then assemble the pieces. Doing it through explicit Expr() objects
# avoids inserting the line number nodes for the macro --- the call site
# is instead explicitly injected into the function body via __source__.
jlfuncsig = Expr(:call, jlfuncname, args...)
jlfuncbody = Expr(:block, __source__, :($statsym = $ccallexpr))
if errexpr !== nothing
push!(jlfuncbody.args, errexpr)
end
push!(jlfuncbody.args, returnexpr)
I’m not sure how much control we have over the URL fragment generation. I think Doxygen guarantees they are stable for a given function prototype, but not much else. I need to dig a little deeper into the Doxygen documentation. I think there was an option to export some kind of a sitemap…
G.
Could we use this patch for doxygen?
gheber
December 23, 2022, 12:48am
5
In doxygen/Doxyfile we specify
GENERATE_TAGFILE = hdf5.tag
I.e., we create the tag file but do not currently use it for anything. Here’s an example:
https://docs.hdfgroup.org/hdf5/develop/hdf5.tag
G.
This is really nice to have so we can easily cross reference downstream documentation with the doxygen documentation.
Hi @gheber is the Doxygen hdf5.tag file available anywhere?
My users are asking if we can still cross reference the documentation:
opened 10:31PM - 25 Mar 25 UTC
The links that normally point to the documentation of low level functions in lib… HDF5 lead to a 404 page. This appears to have been caused by the HDF5 group updating the structure of their website.
For example, the docs for the low level function `HDF5.API.h5_close` references the libHDF5 documentation for `h5close` at this link:
`https://docs.hdfgroup.org/hdf5/v1_14/group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574`
However, this leads to a 404 page. The function is now documented at this link:
`https://support.hdfgroup.org/documentation/hdf5/latest/group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574`
The two main changes to the URL schema seem to be:
* `docs` -> `support`
* `/hdf5/v1_14/` -> `/documentation/hdf5/latest`
Going to `https://docs.hdfgroup.org` tells you to go to `https://support.hdfgroup.org`, so it looks like the HDF group intends this to be the new structure of the website.
I also tried to replace `latest` with `v1_14`, but that leads to a 404 page. I couldn't find a way to get the documentation for v 1.14 specifically, so I'm not sure if the HDF5 group documentation page no longer supports referencing a specific version of the library. It's also possible that there's a link somewhere that I've just missed.
It looks like the files that need to be updated are the two TSV files under `gen/DoxygenTagParser`. I'm not very familiar with Doxygen, so I'm not sure if there is some config file that needs to be edited to edit these files, or if the TSV files themselves need to be edited in their entirety (e.g., by `sed`). If there's some direction here, I am happy to open a pull request with the changes.
I came up with this script to build the hdf5.tag file myself.
curl -fsSL https://pixi.sh/install.sh | bash
pixi global install cmake
pixi global install doxygen
git clone https://github.com/HDFGroup/hdf5.git
cd hdf5
git checkout hdf5-1.14.6
mkdir build
cmake -D HDF5_BUILD_DOCS=ON ..
make -j hdf5hllib_doc
1 Like
byrn
March 26, 2025, 12:29pm
10
Yes, installing that file was overlooked, because we do generate it. Created:#5403 "
Also, I have been attempting to fix the doxygen search box - I can generate the file to index everything, but I have not successfully found an easy method to install the functionality.
Allen
