How to `@ref` a function from a different package?

Tooling
1

From the package FinEtoolsAcoustics I want to reference a function defined in FinEtools. I thought this would work,

!!! note

    The bilinear-form function  [`FinEtools.FEMMBaseModule.bilform_diffusion`](@ref) is used to compute
    the matrix.

but it appears Documenter dropped the specification of the location of this function

image
image705×55 4.69 KB

Does anyone know what the correct incantation would be? I assume it isn’t levioSA?

2

You’d have to make sure that the docstring for FinEtools.FEMMBaseModule.bilform_diffusion is included in your documentation (in a @docs block). If the !!! note is in a docstring itself, you’d also have to make sure there is a binding to FinETools in the module where that docstring is defined. What warning do you see when building the documentation?

Alternatively, you could also use an @extref link instead of @ref, via GitHub - JuliaDocs/DocumenterInterLinks.jl: A plugin for Documenter.jl that enables linking between projects. That assumes you’re generating an inventory in FinETools, though, either with the upcoming release of Documenter, or by loading DocumenterInterLinks in the docs/make.jl file of that package.

I assume it isn’t levioSA?

I don’t know what that means

1 Like
3

Harry Potter reference perhaps

4

Thank you. I was afraid that I was asking Documenter for too much. I will check out @extref!

It is an HP quote (scene from a classroom where the students are attempting to levitate a quill). It seems my assumption that by this time everyone has seen it is wrong… :wink:

5

I will check out @extref !

To expand on my earlier comment, this requires the following steps:

  1. The FinETools documentation needs to be rebuild and deployed with an objects.inv inventory file. If you wait a few more days until Documenter v1.3.0 is released, and you upgrade the FinETools documentation build to use it, this will happen automatically. Until then, if you’re using Documenter >= 1.0, you can add using DocumenterInterLinks to the docs/make.jl file of FinETools. The DocumenterInterLinks contains a backport (actually, the prototype) for the same inventory-writing feature as the upcoming Documenter. If you’re currently using Documenter < 1.0, there’s also GitHub - JuliaDocs/DocumenterInventoryWritingBackport.jl: Backport of inventory writing for Documenter 0.25-1.2, but that’s currently in its 3-day waiting period for registration.

  2. In the docs/make.jl file of FinEtoolsAcoustics, you have to add the following:

    using DocumenterInterLinks

links = InterLinks(
    "FinEtools" => "https://petrkryslucsd.github.io/FinEtools.jl/dev/",
)

makedocs(
    …,
    plugins=[links],
)

    If you made a new release of FinEtoolsAcoustics in step 1, the URL could also be https://petrkryslucsd.github.io/FinEtools.jl/stable/, but in any case, https://petrkryslucsd.github.io/FinEtools.jl/dev/objects.inv or https://petrkryslucsd.github.io/FinEtools.jl/stable/objects.inv needs to exist – that’s what step 1 was about. And don’t forget to pass the links object to makedocs in plugins.

  3. In the FinEtoolsAcoustics documentation, you then reference [`FinEtools.FEMMBaseModule.bilform_diffusion`](@extref). That is, simply change @ref to @extref. See Syntax · DocumenterInterLinks.jl for more details (those might still change, but not in a breaking way).

Again, all of this will switch from “experimental” to “fully supported” (probably) before the end of the month, and going forward DocumenterInterLinks intends to be the full solution for “How to reference a function from a different package.”

4 Likes
6

Small update: DocumenterInterLinks is now stable.

2 Likes