Source link in expanded docstring redirect to Base

[lindnemi]

Our packages has several submodules. In the documentation we have a "Library" subsection that shows the docstrings of all functions intended for public use. Some of the generated source links redirect to our github repo, others incorrectly link to Base. What's going on here?

The relevant page is here: https://fhell.github.io/NetworkDynamics.jl/dev/Library/

[mortenpi]

It looks like it's the ones with Base.@kwdef. Julia probably does not store the correct location information for the docstring in that case. Would need some further investigation though.

[jonathan-laurent]

I have also seen this occurring.
To give another example, you can look at https://juliareinforcementlearning.org/ReinforcementLearning.jl/latest/rl_base/ and then click on the "Source" button for the first documented function.

[mortenpi]

@jonathan-laurent It's also macros confusing the docsystem, just the @api one in your case:

"""
    (π::AbstractPolicy)(env) -> action
Policy is the most basic concept in reinforcement learning. A policy is a functional object which takes in an environemnt and generate an action.
"""
@api abstract type AbstractPolicy end

[jonathan-laurent]

@mortenpi Interesting. I think it would be good to fix this on Documenter's side as prefixing a declaration with a macro call is a pretty common pattern. I stumbled into the same problem in several of my packages and now I understand better why.

[mortenpi]

I agree, but I have a hunch that it might be an upstream bug (the Julia docsystem attaching a wrong path to the docstring).

[mortenpi]

Just a quick follow-up: I believe the way to work around this is to attach the docstrings with the @doc macro. I.e. something like this:

@with_kw struct A
  a::Int = 6
  b::Float64 = -1.1
  c::UInt8
end

@doc """
    struct A
""" A

[bzinberg]

As mentioned in JuliaLang/julia#36906 (comment), that workaround (which I have also been using for a while) is very helpful but loses field docstrings.

[mortenpi]

This should be fixed on 1.6 JuliaLang/julia#37048, so no workaround should be necessary if you build the documentation on 1.6+.