Inter-Module at-refs?

[har7an]

Hello,

I've started using Documenter yesterday and I'm afraid that my experience has been most frustrating so far. I'm trying to document a package I write at work that consists of a bunch of submodules, where the docs in the submodules refer to each other at some points. I want these refs to be actual URLs (not just verbatim text) so users of the docs can find the relevant bits easier. I've condensed my problem into a MWE, hosted here: https://github.com/har7an/julia-documenter-inter-module-docs

Maybe I'm just using it wrong and I missed a crucial step in all of this, but I can't get the docs in module C to reference B.Blarg. I build the docs in that project with these commands:

$ cd docs
$ julia --project make.jl

As you will see in the output I get a lot of warnings. In the finished docs, none of the 5 at-refs I tried works and I don't understand what's wrong. Can someone please help me?

As a sidenote, I'm primarily a Rust developer and so far Documenter seems to introduce a lot of friction into the documentation process compared to e.g. rustdoc. Is there a way to make the docs build entirely from the code in src/ only like you do in Rust? I don't need anything else, really.

[Michael Goerz]

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).

[Michael Goerz]

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.

[har7an]

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?

[Michael Goerz]

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.

[har7an]

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.

[Michael Goerz]

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.

[Michael Goerz]

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.

[har7an]

Thanks for picking this up so quickly and fixing the issue @goerz!

Looking forward to the next release now so I can stop using the patched version of Documenter.

[Michael Goerz]

Me too! :-)