Inter-Module at-refs? about documenter.jl HOT 9 OPEN

The problem is that Blarg or B needs to be defined in C in order for the docstring being able to reference it. So you have to put import ..B or import ..B: Blarg in the definition of C.

It's indeed a quite annoying, but I'm not sure what a "correct" solution would be. If you write [`Blarg`](@ref) somewhere, how is Documenter supposed to know which Blarg you are referring to? It's something I might play around with solutions for, though, see the last paragraph in #2453 (comment)

One possible solution might be for Documenter to fall back on Main if it can't get a binding in the module where the docstring is defined. This would mean that you could import Blarg in your docs/make.jl file, and then any reference to Blarg would fall back to that if necessary. Realistically, that would work quite well at least for the fully qualified name (JDIMD.B.Blarg, in this case).

from documenter.jl.

Is there a way to make the docs build entirely from the code in src/ only like you do in Rust?

That might be the intent behind #2353, although for now, a "minimal" setup that just includes an @autodocs block would pretty much do that. That does not get you around the limitations of Julia markdown, or this issue, though.

from documenter.jl.

Thanks for the swift replies!

a "minimal" setup that just includes an @autodocs block would pretty much do that.

I was wondering about that already. Something like:

```@autodocs
Modules = [TOPLEVEL]
```

seems to only document what's directly beneath that entry, unless I'm missing something. Can autodocs be recursive?

from documenter.jl.

No, you have to list all the (sub-)modules. Theoretically, the right-hand-side of Modules = can be Julia code that's evaluated in Main (what you define in docs/make.jl), so you might be able to do something with that to get the list of submodules programmatically.

from documenter.jl.

The problem is that Blarg or B needs to be defined in C in order for the docstring being able to reference it. So you have to put import ..B or import ..B: Blarg in the definition of C.

I see. That's a pretty hard limitation in my opinion, because:

• I have to at least import items into my code that aren't used in the code but only the docs
• This runs into the same sort of issue as regular "module resolution", where a type must be defined in an "earlier" module to be used. IIUC this makes it impossible to have some F.Foo reference a B.Bar and vice-versa.

Thank you very much for the feedback! Knowing about the limitations of Documenter, I'll try my luck writing the documentation in Sphinx for now.

from documenter.jl.

I agree with your diagnosis on the limitations or docstring-@refs.

As far as Sphinx is concerned, you might run into more frustrations there. I don't think there's any support for including Julia docstrings in Sphinx, since https://bastikr.github.io/sphinx-julia/ is no longer functional (as far as I could test out). If you do manage to make a Sphinx setup work, I'd be interested to hear about it.

At least as a technical curiosity – more generally, I would recommend trying to stick it out with Documenter. There is value in having a uniform documentation setup with Documenter throughout the ecosystem, just like with virtually all Python packages using Sphinx. Like any system, Documenter has its warts and idiosyncrasies, but once you get over the initial hump of unfamiliarity, it is quite a capable system.

from documenter.jl.

I'm actually going to reopen this, since I think

One possible solution might be for Documenter to fall back on Main if it can't get a binding in the module where the docstring is defined

is something we should very much consider (@mortenpi). I might want to prototype that first, though, with the help of #2453, to see how well it works in practice.

from documenter.jl.