-
Notifications
You must be signed in to change notification settings - Fork 231
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
How to fix "Rd warning missing file link" when linking to an alias #707
Comments
Markup was used to link to help documentation for base::package_version() in @details and utils::packageVersion() in @return, but those functions do not have individual help files. Instead, they link to the common help files for base::numeric_version() and utils::packageDescription() respectively. Because the markup approach does not allow to point to the common help files ala r-lib/roxygen2#707, the markup was replaced with corresponding roxygen formatting commands. This patch will remove the error messages for missing files during package installation.
This issue seemed still exist, it's also reported for other users after the supposed fix. Installing package in Mac don't have the warning, but installing same package in windows has it. The actual link in help is working in both case. I'm not sure why there is difference in platforms. |
This change will prevent Rd warnings during "Install and Restart" on Windows. However, it may make the link more fragile. r-lib/roxygen2#707 https://stackoverflow.com/questions/48430093/how-do-i-resolve-rd-warning-missing-file-link-when-building-packages-in-rstudi/48478698#48478698
This change will prevent Rd warnings during "Install and Restart" on Windows. However, it may make the link more fragile. r-lib/roxygen2#707 https://stackoverflow.com/questions/48430093/how-do-i-resolve-rd-warning-missing-file-link-when-building-packages-in-rstudi/48478698#48478698
See issue description here: r-lib/roxygen2#707
This change will prevent Rd warnings during "Install and Restart" on Windows. However, it may make the link more fragile. r-lib/roxygen2#707 https://stackoverflow.com/questions/48430093/how-do-i-resolve-rd-warning-missing-file-link-when-building-packages-in-rstudi/48478698#48478698
* Link to topic file rather than alias This change will prevent Rd warnings during "Install and Restart" on Windows. However, it may make the link more fragile. r-lib/roxygen2#707 https://stackoverflow.com/questions/48430093/how-do-i-resolve-rd-warning-missing-file-link-when-building-packages-in-rstudi/48478698#48478698 * Manually restore fixes from this PR * http --> https * Add a NEWS bullet
I confirm that this problem (the warnings at install time) appears to be Windows-specific. So when this gets tackled, that platform is the main one to test on. I changed the affected usethis templates to link to Rd files, not topics, which cleared the warnings during installation on Windows. Most relevant section of WRE is 2.5 Cross-references, especially this paragraph (although I beg to differ re "rarely needed"):
|
Is this really causing any problems? I have packages on CRAN that produce this warning, but seemingly CRAN is fine with this. |
No, I don't think this causes problems. I see lots of packages emitting tons of these warnings when installing on Windows. I think silencing the installation warnings is just good from a "not crying wolf" POV. And the wording of WRE somehow gives me a sense that CRAN could decide to care about this one day, since they refer to it as "misuse". |
Well, I think that while this is undesirable, it is perfectly normal. This is what namespaces are for. Having to link to the name of the file is not ideal at all. You would want to be able to link to an exported function or to a topic, that's the right level of abstraction. That is also independent of how the help topics are organized into files. So personally, I would not worry about this, until it really becomes an issue. |
Fair enough. I agree that you really should be able to link to another package's function or topic and be insulated from how that maintainer chooses to document it. |
FWIW, I also get this with rstudio server on an RHEL AWS box. I can't easily reprex, 'cuz I'm linking from one internal company package to another, but the links are like this: And that help is actually in @rdname generate_sql It isn't really an issue, it just makes scary noise when I document. The one thing I worry about is that it'll mask an actual error at some point (because I'm used to seeing a bunch of output there). |
It seems like this is bugging more folks than me, so I have put together a potential solution at https://github.com/rabutler/roxygen. It modifies This does come at some expense. After this addition, using microbenchmark and an examle taken from the tests (included at the end), the median execution time increased from 37 ns to 272 ns. I think this is likely because it currently calls If this concept seems reasonable and useful, then I'll spend some more time to improve the efficiency. Additionally, I have a few questions that would be good to get the package authors to weigh in on:
Code to check evaluation time:
|
First of all, this is not a roxygen issue. If you write your documentation without roxygen, in Rd files, then you still get the warnings. Second, you already have an option to link to the file, as above:
Third, I think linking to the file is not right. You should not rely on or care about which file documents certain functions and topics. Should that change, your documentation links will be broken. If you link to a function name, that will work, as long as that function is still exported from the linked package. I understand that the warning is annoying. I think we should try to fix this in base R, simply by avoiding the warning. |
@rabutler This said, my third point is subjective, and getting this fixed in base R might not be simple, so if you open a PR, it might get merged, still. :) So thanks for investigating this! |
Thanks @gaborcsardi I appreciate the thoughts. I understand it's not an roxygen issue, but to your last comment, thought it might be easier to address in roxygen than base R, especially since roxygen is parsing these files already. I think my proposed fix actually prevents the user from having to link to the file. If you use However, if you stick with the markdown version Either way, thanks for considering. I'll clean up a bit more, and try to not call |
The installed version of the linking package will break with the new dplyr version, and it would need to be reinstalled. |
Wouldn't that also be the case if you were using |
Sure. That's why just linking to the function name is better. |
@gaborcsardi not sure what you mean by "it is only used for new submissions", but a new version of my already-on-CRAN package was just bounced with this on the CRAN Debian pretest (it passes without warning on their Windows machine):
|
They do not use it in their daily checks, and they'll not archive packages because of this. But they'll enforce it for newly submitted versions, new packages included. |
Background: https://cran.r-project.org/doc/manuals/R-exts.html#Cross_002dreferences https://community.rstudio.com/t/file-link-quasiquotation-in-package-rlang-does-not-exist-and-so-has-been-treated-as-a-topic/55774/2 r-lib/roxygen2#707 (comment) I got the syntax from the PR below: https://github.com/Rdatatable/data.table/pull/4011/files
A warning on Windows r-lib/roxygen2#707
|
@chilampoon The file name has changed in dplyr. Also, linking to topics/files has changed in R itself as well, so what works with one R version might not work with another. |
Okay, I didn't use the dplyr function to test actually, but just found that [pkg-pageName] didn't work on my end with R 4.0.3. |
Actually, the file name hasn't changed, the dash must have been a typo. |
But also, with R-devel and recent roxygen you should not need to do that. That's why this issue is closed. |
@gaborcsardi I got a Rd warning in a Windows platform check for my package, something like I found that the 'function' is documented with several other functions in a single help page, that's why |
If you write |
Yea, writing the |
Currently, if you link to a function in another package that has an alias that points to a different Rd/html file, you end up with a missing file link warning when building the package.
For example, if your documentation includes:
You end up getting the following warning when building the package:
As was pointed out on Stack Overflow, you can resolve this by linking to the file, instead of the alias:
However, I don't think you can do this if using the markdown version. It also seems slightly dangerous to link to a RD/html file, which seems more likely to change than a function name; at least it seems possible that a developer might change the Rd file names without thinking of the issues, while function names are at least deprecated first.
So, would it make sense to search the
.libPaths()
usingtools::findHTMLlinks(level = 2)
, while roxygen2 is converting the Roxygen comments to Rd files, and add in the appropriate file link for any functions that uses aliases to point to a different file name?I'm not sure how much extra overhead this would add, but it would make reading the build messages a little nicer.
The text was updated successfully, but these errors were encountered: