New vs Old Documentation URLs

kittisopikulm · May 25, 2022, 8:26pm

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

github.com

JuliaIO/HDF5.jl/blob/0ac00d1ce63a10e4a4e8e3768dcb1efb1f1c1b5d/gen/bind_generator.jl#L229


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)

gheber · May 27, 2022, 6:28pm

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.

kittisopikulm · December 22, 2022, 10:43pm

Could we use this patch for doxygen?

kittisopikulm · December 22, 2022, 10:54pm

Is the tag file available?

https://www.doxygen.nl/manual/config.html#cfg_generate_tagfile

gheber · December 23, 2022, 12:48am

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.

kittisopikulm · December 23, 2022, 1:02am

This is really nice to have so we can easily cross reference downstream documentation with the doxygen documentation.

gheber · December 23, 2022, 12:46pm

kittisopikulm · March 25, 2025, 10:46pm

Hi @gheber is the Doxygen hdf5.tag file available anywhere?

My users are asking if we can still cross reference the documentation:

github.com/JuliaIO/HDF5.jl

Links to low-level function documentation in libHDF5 lead to a 404 page

opened 10:31PM - 25 Mar 25 UTC

fergu

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.

kittisopikulm · March 25, 2025, 11:42pm

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

byrn · March 26, 2025, 12:29pm

Yes, installing that file was overlooked, because we do generate it. Created:
" Install doxygen tag file #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

kittisopikulm · July 17, 2026, 9:14pm

I am hunting for the tag file again. I’m not sure if anything changed but HDF5_BUILD_DOCS was incorrect in my previous post. The correct cmake parameter is HDF5_BUILD_DOC.

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_DOC=ON ..
make -j hdf5lib_doc

hdf5.tag should then appear in the current build directory. make install currently installs this to share under the install prefix.

I’ve created a pull request to move this into share/html which the documentation. My hope is that it will then be carried with the HTML documents to the website so that it can be accessed via http://support.hdfgroup.org/documentation/hdf5/latest/hdf5.tag

Attention! https://support.hdfgroup.org is the NEW home for documentation from The HDF Group. (Details)

New vs Old Documentation URLs