search

r-lib / roxygen2

Generate R package documentation from inline R comments
https://roxygen2.r-lib.org
Other
585 stars 231 forks source link

Always resolve to "anchored" Rd xrefs #1612

Open jeroen opened 3 months ago

jeroen commented 3 months ago

In order to improve cross-package links in the new single-page-html documentation, CRAN will start showing NOTEs for Rd pages which link to a topic that exists in multiple CRAN packages, such as toJSON (in jsonlite, RJSONIO, rjson).

Seemingly it is not trivial at CMD check time to resolve a topic to a given based on the package imports/suggests. They suggest you use "anchored" Rd links, which simply means using the full \link[pkg:topic]{topic} syntax.

If possible, way to reduce some of the fallout would be to resolve a [topic] name to the full \link[pkg:topic]{topic} at roxygenize time, by inspecting at the package namespace, i.e. to automatically determine the pkg: value when unset:

https://github.com/r-lib/roxygen2/blob/2357de6fe50df352f286a4ec77f65e00e582fa21/R/markdown-link.R#L12-L23

gaborcsardi commented 2 weeks ago

Seemingly it is not trivial at CMD check time to resolve a topic to a given based on the package imports/suggests.

...

If possible, way to reduce some of the fallout would be to resolve a [topic] name to the full \link[pkg:topic]{topic} at roxygenize time,

So, to be clear, they don't want to do this, but they want us to do it? :D

gaborcsardi commented 2 weeks ago

Btw. anyone knows a package that has this issue?

gaborcsardi commented 2 weeks ago

Btw.2. Is this change documented anywhere? I can't see anything in `Writing R Externsions'. It would be good to know the rules before we update roxygen2. E.g. are unqualified links to base packages allowed?

jeroen commented 2 weeks ago

You can probably email kurt directly, he presented about this today. I would guess all cross package links need to be anchored, incl base.

Op di 9 jul. 2024 20:41 schreef Gábor Csárdi @.***>:

Btw.2. Is this change documented anywhere? I can't see anything in `Writing R Externsions'. It would be good to know the rules before we update roxygen2. E.g. are unqualified links to base packages allowed?

— Reply to this email directly, view it on GitHub https://github.com/r-lib/roxygen2/issues/1612#issuecomment-2218402227, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABUZ74LQNXNBMCFK35FVU3ZLQVFPAVCNFSM6AAAAABGRITATSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMJYGQYDEMRSG4 . You are receiving this because you authored the thread.Message ID: @.***>

gaborcsardi commented 2 weeks ago

From the check message it seems that references to base packages do not need to be qualified:

  Please provide package anchors for all Rd \link{} targets not in the
  package itself and the base packages.