Cross reference between modules
orenbenkiki opened this issue · comments
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?
Does it work if you import all modules into Main in make.jl?
I did:
- Upgrade to Documenter 1.4.0
- Put
using MyPackage
indocs/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!