Allow the pkgdown site to be created within inst, so that it can be viewed locally by users who have installed the package
cararthompson opened this issue · comments
I'm working on a package for a client, and have written documentation and tutorials using {pkgdown}. These need to remain private.
I'd love to use something like browseURL() to allow them to open the nicely formatted documentation in a browser from within the package, but docs doesn't seem to make it into the built package. Is it possible to overwrite the destination folder of the site so that it's within inst? If not, would that be something others would find useful? Have I missed something obvious?
I can copy the folder across to inst for now, but I'm hoping there's a more elegant solution. Thanks!
@cararthompson there's a destination parameter https://pkgdown.r-lib.org/reference/build_site.html#general-config, you could try setting it to inst/docs or so?
Note that the search functionality won't work with browseURL() so the users would need to do something like servr::httw(system.file("docs", package = "pkgname") or so. https://pkgdown.r-lib.org/reference/build_search.html?q=servr#debugging-and-local-testing
Great, thanks for the speedy response! I had system.file() as part of the solution, but thanks for the extra tip!
I feel I'm being silly, but where do I edit the general config?
@cararthompson not silly! in a file called _pkgdown.yml https://pkgdown.r-lib.org/articles/pkgdown.html#metadata or via the override argument of build_site() https://pkgdown.r-lib.org/reference/build_site.html
Aha, perfect. Thank you!
Please report once you've tried, in case we can close the issue. 🍀
Here's what I did, which works just as I wanted it to.
In the _pkgdown.yml file, I added destination: "inst/docs/" at the highest level of the hiearchy.
destination: "inst/docs/"
template:
bootstrap: 5
etc...
Then, I created a wrapper function to allow users to easily view the documentation:
open_documentation <- function() {
browseURL(system.file("docs/index.html", package = "mypackage"))
}
If I use servr::httw(system.file("docs", package = "mypackage") it opens the index of the documentation in the viewer pane, but I feel the browser is a better fit for this use case.
browseURL seems to do what I need if I specify the index.html file. Is there anything I should be mindful of in doing that instead of using servr::httw()?
If you assign servr::httw(system.file("docs", package = "mypackage") to an object say x <- servr::httw(system.file("docs", package = "mypackage") then you can use browseURL(x$url).
this way the users would browse a website where search works.
Aha, great. Thanks.
One final question. Can I get the documentation to open only in a browser, not in the viewer pane as well as the browser? servr::httw() seems to force it to open and prints a message in the console about how to use servr::deamon_stop(). I can suppress the message, but is there a cleaner solution?
servr::httw(<path>, browser=FALSE, verbose=FALSE) seems to do the trick!
Perfect. I've just implemented that and it works exactly as required.
Thank you so much for your help!
Happy for the issue to be closed.
Awesome, great to hear!