Issues with package extensions

[mateuszbaran]

I'm working on introducing package extensions to one of my packages: https://github.com/JuliaManifolds/Manifolds.jl/pull/607 . I've encountered some issues that would be most easily explained by Documenter not loading (or not noticing) the code from extensions.

First, docstrings written in a package extensions are not rendered even if the extension is loaded in the Julia session from which Documenter is triggered.

~~Second, @example block don't seem to load package extensions when their code is executed which leads to errors that don't happen when the same code is just executed in a new Julia REPL.~~

I'm not 100% sure if these are Documenter.jl bugs but maybe someone has experienced similar issues?

[mortenpi]

Do you happen to have an MWE where I could try this out? The Manifolds example is a bit heavy. It would be nice to have a simple (e.g. Example.jl-based) repo, with some trivial examples, to test this.

[mateuszbaran]

I've prepared an MWE here: https://github.com/mateuszbaran/MWE2124.jl . The issue with @example block looks unrelated to Documenter.jl but the docstring for the method defined in extension doesn't appear in documentation, even though Base.@doc sees it:

julia> Base.@doc MWE2124.hello
  hello(who::String)

  Return "Hello, who".

  hello(who::Int)

  Return "Hello, number who".

[mateuszbaran]

I've found a workaround: passing the extension module to makedocs: https://github.com/JuliaManifolds/Manifolds.jl/pull/607/commits/4203a96c3684360fed5b40a41bff615eac0ede06#diff-4aae2d1c783cade58bd2cb13748da956e568b7f2aed5fafd9e2a46fb97daf613L73-R77 . Maybe it would be a good idea to document this pattern somewhere?

[mortenpi]

Yeah, that's what I presumed you'd need to do, since they're their own modules. Having some notes about it in the Documenter manual would be useful I think.

[oschulz]

Thanks for the workaround @mateuszbaran !

[rafaqz]

Thanks @mateuszbaran .

It would be good to automate this in Documenter too. I assumed that loading the packages in the make.jl file would make the extension docs available. It seems more natural to do that than to explicitly get the extensions like that.

[codetalker7]

I've found a workaround: passing the extension module to makedocs: JuliaManifolds/Manifolds.jl@4203a96#diff-4aae2d1c783cade58bd2cb13748da956e568b7f2aed5fafd9e2a46fb97daf613L73-R77 . Maybe it would be a good idea to document this pattern somewhere?

Hi. Related to this issue: I had a few docstrings in a package extension which I wanted to include in the main docs, without having to load the trigger package for the extension (because, the trigger package was a GPU package, and my system doesn't have support for that particular GPU). It seems that the trick mentioned here doesn't work for this case. It would be great if there was some functionality in package extensions to fetch only docstrings from extensions (without having to install trigger packages or run extension code).

[kbarros]

It seems that the @autodocs feature of Documenter is unable pick up the doc string that is defined by ExtensionPackage.

Consider a main package with a stub function:

function extension_function end

Then an ExtensionPackage defines a method with an attached doc string:

"""Long doc string"""
MainPackage.extension_function() = println("hello world")

Doing @doc extensions_function will correctly show the doc string. However @autodocs does not pick it up.

Edit. A workaround is to include the docs through explicit @docs blocks that go after the @autodocs command.

```@docs
extension_function
```

[BambOoxX]

Is there a way to document internal functions in extensions ? Although they are not accessible in the main package, a documentation may be a relevant source of information...