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.
