Resolve markdown links to external packages

[gaborcsardi]

• Anchor links to base packages as well.
• Do not anchor base packages.
• Tests.
• News.
• Docs.
• Cache dependency info.
• Resolve re-exported functions.

Closes #1612.

[krlmlr]

Works for me in duckdb, thank you for the very quick fix!

[krlmlr]

Super-minor stuff.

Next level: automatically add these qualifications with @inheritParams -- I have this in DBI, and I see how niche this probably is.

[gaborcsardi]

@krlmlr

Next level: automatically add these qualifications with @inheritParams -- I have this in DBI, and I see how niche this probably is.

You mean adjusting the link target packages in Rd from @inheritParams? Doesn't that work already?

[krlmlr]

This might work, I have only tried with \linkS4class{} where it doesn't.

[krlmlr]

It changes things in tibble, trying in CI/CD now: https://github.com/tidyverse/tibble/actions/runs/9871752503

Thank you very much!

[krlmlr]

Works for tibble, green builds again!

[gaborcsardi]

So, I have been using this for a bit, and it does not work very well when you are adding new functions that are not documented yet, or refactoring a package and renaming functions. The errors don't allow the changes to propagate properly.

One solution would be to have a warning instead of an error. This is easy to implement. The caveat is that you might end up with incorrect links, unless you run document() twice.

Another solution is to delay the resolution of the link target packages until the (new) topic of the documented package are known. This might be difficult to implement with how roxygen2 works currently. We would essentially need to do the final link fixup in the generated Rd docs.

[krlmlr]

To better understand this: the problem is that this PR works worse than the main branch if documentation is added to a function that didn't have documentation before? What errors are you seeing?

[hadley]

I think switching to warnings are probably a good start. Can we assume that if we can't find the topic it's in the current package?

[gaborcsardi]

Good idea. R CMD check will catch the real errors anyway.

[gaborcsardi]

@krlmlr Yeah, when you are refactoring or developing, you might have a state where you are referring to a function that is not documented. E.g. if you simply rename a function that you are cross-linking from a manual page. With this PR the package of the renamed function cannot be resolved, which causes an error, and the manual pages are not updated. So you are stuck in this state.

[gaborcsardi]

@hadley OK, I turned them into warnings. Can you please take another look?

[jeroen]

Great, this worked for all cases I tried!