New vs Old Documentation URLs

kittisopikulm · 2022-05-25 20:26:27 UTC

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 · 2022-05-27 18:28:03 UTC

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.