Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Alias docstring not found #2087

Open
tecosaur opened this issue Mar 27, 2023 · 6 comments
Open

Alias docstring not found #2087

tecosaur opened this issue Mar 27, 2023 · 6 comments

Comments

@tecosaur
Copy link

I have a package that re-exports some symbols from another packages of mine.
In the Documenter.jl-generated docs, I see "Missing docstring for DataToolkit.@addpkg. Check Documenter's build log for details.", but in the Julia REPL the docstring appears without issue.

image

image

So, it would appear that Documenter.jl has a problem with aliases.

@mortenpi
Copy link
Member

DataToolkit.@addpkg is just a pointer to the original object though (something like DataToolkitBase.@addkpg I presume), and the docstring is attached to that. So I am not sure the behavior here is actually incorrect. If you put DataToolkitBase.@addkpg in at-docs, it should pick up the docstring I think?

@tecosaur
Copy link
Author

I could put that, but I'm listing it in the documentation as an exported symbol of DataToolkit so having the docstring show DataToolkitBase would not be helpful.

It is an alias, but might it be possible for Documenter.jl to resolve the docstrings for the symbol in the same way as help?>? I'd think that would be the most correct/intuitive behavior.

@tecosaur
Copy link
Author

An update on this, trying DataToolkitBase.@addpkg doesn't work. This is with and without a using DataToolkit.DataToolkitBase in docs/make.jl. I've also tried DataToolkit.DataToolkitBase.@addpkg, still no luck 😞

In the build logs, I just see:

Warning: no docs found for 'DataToolkitBase.@addpkg' in `@docs` block

In the meantime, having a quick look at Documenter vs Docs, I see this:

juila> using .Docs

julia> using Documenter

julia> bind = Docs.Binding(DataToolkit, Symbol("@addpkg"))
DataToolkit.@addpkg

julia> bind == Documenter.DocSystem.binding(DataToolkit, Symbol("@addpkg")) 
true

julia> Documenter.DocSystem.getdocs(bind, Union{Tuple{}}; modules = [DataToolkit])
Base.Docs.DocStr[]

julia> Docs.doc(bind, Union{Tuple{}})
  @addpkg name::Symbol uuid::String

  Register the package identifed by name with UUID uuid. This package may now be used with @import $name.

  All @addpkg statements should lie within a module's __init__ function.

  Example
  ≡≡≡≡≡≡≡≡≡

  @addpkg CSV "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

I'd be curious to know why Documenter doesn't use Docs.doc for this?

@mortenpi
Copy link
Member

mortenpi commented Jun 15, 2023

I'd be curious to know why Documenter doesn't use Docs.doc for this?

I think we'd need Michael from 8 years ago to answer this question 😆 Not at all sure, but possibly because Documenter predates Docs.doc (at least in some form). The whole docsystem integration could use a refactor.

That said, I am also not immediately sure that Docs.doc does the "correct thing" necessarily (would need some thought to figure out if it does or doesn't). Documenter's at-docs blocks do not try to fully emulate the REPL, since that can take control away from you when you author the at-docs blocks.

@tecosaur
Copy link
Author

I just thought I'd comment that I'm still trying (and failing) to get this to work.

@mortenpi
Copy link
Member

mortenpi commented Sep 29, 2023

What if you pass DataToolkitBase to makedocs(modules = ...)? And then refer to it with DataToolkitBase.@addpkg? E.g. Documenter's own docs include docs from other packages and it works:

modules = [Documenter, DocumenterTools, DocumenterShowcase],

It would still show DataToolkitBase in the docstring header, but you should be able to get it included at least.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants