Documenter.jl: Broken links when reexporting package

[nalimilan]

Currently building the docs for DataTables prints this error:

> checking footnote links.

Documenter: populating indices.

Documenter: rendering document.

 !! Invalid local link: unresolved path

    '@ref' in lib/utilities.md

 !! Invalid local link: unresolved path

    '@ref' in lib/utilities.md

 !! Invalid local link: unresolved path

    'utilities.html#DataTables.nonunique' in lib/utilities.md

The error is quite cryptic since @ref does not actually appear in lib/utilities.md, but in a docstring included there. Once I figured that, I realized looking at generated HTML files that @ref came from a [`levels`](@ref) link which is in the docstring for unique in CategoricalArrays.

The problem comes from the fact that DataTables @reexports CategoricalArrays, which implements Base.unique. So its docstring is added to the manual after the one for the method defined in DataTables. But levels, which is referenced in the docstring, is not documented in DataTables, only in CategoricalArrays, so the link is broken. We could list levels in the manual, but it's not completely related to DataTables so I'd rather not do that if that's possible.

Would there be a way of detecting these cases and avoid including the docstrings for reexported functions? In general I don't think you want to include all docstrings from a reexported package in the other packages' manual: functions are reexported for convenience, but it can be confusing to document all of them, some of which might not be completely related to the reexporting package.

[mortenpi]

Is the last one (utilities.html#DataTables.nonunique) caused by #505 by any chance? I.e. the docstring that has the link is included twice somehow?

As for re-exports -- I think it sounds reasonable to not include those docstrings by default. We should probably have a way of explicitly specifying that you want re-exported ones as well when listing methods in an ```@docs-block. We should probably handle @refs a bit more intelligently as well -- e.g. this is sort of a valid case for a broken link, so we should probably semi-quietly just drop the link or something.

Also, I completely agree that the errors are completely cryptic, so ideally they should be improved. Unfortunately I have to say that I don't think I have time do get to any of this myself in the near-future. PRs would be most welcome though.

[nalimilan]

Thanks, makes sense. I understand that you don't have the time to fix all bugs, but there's no real hurry for us.

Is the last one (utilities.html#DataTables.nonunique) caused by #505 by any chance? I.e. the docstring that has the link is included twice somehow?

I don't think that's the case, as grepping for nonunique returns a single occurrence in the docs/ dir. Or maybe there are other ways by which that could happen?

[lbenet]

As for re-exports -- I think it sounds reasonable to not include those docstrings by default.

Is there a way to not include re-exports?

[mortenpi]

Is there a way to not include re-exports?

I don't think so, as this has not been addressed yet. What would help to spur this a bit would be to have a tiny MWE repo showing how re-exports are currently handled and what the expected behavior should be.