Cross reference between modules

[orenbenkiki]

Julia (wisely) prevents circular dependencies between modules. However, in the documentation, it is often useful to reference something in a dependent module (e.g., "this function/type only does basic X functionality, see [..DependentModule.Y](@ref) for the common specialized Y behavior).

However, the way Documenter works is that any symbol referenced by the documentation must be also available to the module's code as well. This makes it impossible(?) to create such links.

I assume this is because Documenter somehow looks at each sub-module of the package separately and incrementally in a single pass. FWIW, Python's sphinx doesn't has this restriction - it does a two-pass on the documentation, one pass collecting everything across the whole package and a second one resolving the intra-package cross-module links.

I therefore expect this isn't easy to fix... Still, I find this hampers creating thorough documentation. It would be useful if this could get fixed at some point. Or - is there some workaround for this problem I have missed?

[fredrikekre]

Does it work if you import all modules into Main in make.jl?

[goerz]

Specifically, with Documenter 1.4.0, which included a fix for https://github.com/JuliaDocs/Documenter.jl/issues/2462 (probable duplicate of this issue)

To be clear: you will have to use fully qualified names in the link, but that’s a deliberate design choice

[orenbenkiki]

I did:

• Upgrade to Documenter 1.4.0
• Put using MyPackage in docs/make.jl
• Used the full name as the target reference: [...](@ref MyPackage.MyModule.name)

And now I can refer to anything from everywhere regardless of import and using statements in my modules.

Thanks!