Unfortunately .install_extras does not preserve folder structure

This is not true, you can copy folders with the full structure. But you have to be careful how you construct the regular expression in .install_extras.

E.g. if I want to copy the test folder and containing files in vignettes/test you need to only have

^vignettes/test$

In your .install_extras file. Using $ to restrict to only matching the folder is important.

I stand corrected, thank you for pointing this out :)

One thing though is that Doxygen documentation is not negligible in size -- about 100KB (compressed) of overhead for any project (but scales relatively well with project size). So, if possible I'd like for the Doxygen doc not to be duplicated for the purpose of uploading to CRAN.

Would love to hear your thoughts on this if you get a chance.

Actually this can be achieved by adding a line to .Rbuildignore.

Anyways, thank you very much for your help.

Out of curiosity, would it be possible to answer the original question? I really would like to benefit from your insights as to why the standard source location for package documentation ought to be changed from inst/doc to vignettes.

It is extremely common for authors to mistakenly have stale vignette outputs in inst/doc, and very rare to have non-vignette generated docs.

Thank you for the explanation -- this makes perfect sense.

Might you consider a minimal PR to make the deletion by default but optional? I was thinking along the lines of a clean_inst_doc argument to pkgbuild::build, with default value TRUE producing exactly the same behavior (i.e., with interactive prompt) as the current setup...

@mlysy that will not take you very far, because pkgbuild is often called downstream, e.g. by rcmdcheck or remotes::install_github() where you cannot supply any arguments.

I realized this (too late), and would have liked to amend my suggestion to the prompt asking whether or not to delete inst/doc, but not to exit prematurely if the answer is "no" (and not to delete outside of interactive() mode, in which case I should think there's less risk of passing forward stale contents of inst/doc to the build).

Forgive me for being persistent, but I do hope there is some value in encouraging R package developers to better document their C++ source code, for which Doyxgen (in my mind) is the ideal software. Due to the ubiquitous usage of devtools/pkgbuild among these developers, I think it is important for rdoxygen to be fully compatible with it.

I should also point out that the approach above of

1. putting the Doxy doc in vignettes/doxygen,
2. sending it to inst/doc on build via .install_extras,
3. and .Rbuildignoreing the vignettes copy so as not to waste space on CRAN

breaks if devtools::install() or pkgbuild::build() is (re-)run on the extracted tarball, as vignettes/doxygen in the extracted source no longer exists...

Therefore, might a PR to the effect of modifying the prompt from "accept that inst/doc will now be delete" to "decide whether inst/doc will now be deleted" be something that you would consider?

This setting belongs to the package, so ideally, you would be able to request this behavior in DESCRIPTION.

But can't you just put the docs in inst/docs or inst/cdocs or something like that? Doesn't that solve this issue?

The problem is that if we wish to access the Doxygen doc as a vignette, our HTML redirect (see above) only works for installed packages if the Doxy doc is in a subfolder of doc (more info here). The exact error message (displayed in the web browser) is:

Only help files, NEWS, DESCRIPTION and files under doc/ and demo/ in a package can be viewed

I suppose we could backdoor the Doxygen doc through inst/demo (haven't tested this yet), but I'm still clinging to the hope that a minor modification to pkgbuild would be preferable...

I see. Then maybe a custom field in DESCRIPTION that tells pkgbuild not to delete (some of?) these files, is the best solution.

If this is something that you (the developers of pkgbuild) would be open to, then it would be my utmost pleasure to submit a PR. Just let me know :)

I think for sg like pkgbuild, that is often called downstream, it makes sense to have config in DESCRIPTION.

@jimhester what do you think?

I still don't understand this behavior (after reading through this discussion).... probably because I'm just too stuck in my ways. My current (probably soon-to-be-former) process for checking my package before sending it to CRAN was:

1. Click the "Install and Restart" button in RStudio
2. Run devtools::build_vignettes() to absolutely make sure I had the current versions of the vignettes in the inst/doc folder
3. Run tools::compactPDF on any old-school .Rnw vignette
4. Click the "Check" button in RStudio (4.5 cross fingers...)
5. Click the "Build Source Package" and send that file to CRAN assuming no notes/warnings/errors

Now I'm just nervous about everything. I can't run check() without deleting the inst/doc folder. build_vignettes doesn't put the vignettes there anyway. So, via devtools - I will always get a warning for not compacting the pdf vignettes (right?).I have to live with the Warning, move the doc folder manually into inst/doc, run tools::compactPDF, then build the source.

Am I just living in the past and there's a better way to develop packages now?

"inst/doc" is still the canonical home for vignettes on CRAN, correct? ie...CRAN doesn't rebuild the vignettes, or has that changed? I'm basing my understanding on:
https://stat.ethz.ch/pipermail/r-package-devel/2017q1/001273.html

I would just use use devtools::build(vignettes = TRUE) to build the package with vignettes, then send that to CRAN.

I know this is an old thread but inst/doc seems to be required to build vignettes. Having vignettes in vignettes does not build vignettes as required. Is there a workaround?

I arrived here due to a similar issue. Basically, when I develop a package for a client, I sometimes have several very big vignettes with expensive computations that I want to build once and keep both the static HTML/PDF and the Rmd.

FYI, I found a nice solution. I put those Rmds under vignettes, but without any VignetteIndexEntry stuff in the YAML header. Then, I call rmarkdown::render whenever I want to build them. And, finally, I follow the instructions here to include static vignettes.

TL;DR:

$ ls -1 vignettes/
test.html
test.html.asis
test.Rmd
$ cat test.html.asis
%\VignetteIndexEntry{Test vignette title}
%\VignetteEngine{R.rsp::asis}
%\VignetteEncoding{UTF-8}

And add R.rsp to Suggests and VignetteBuilder in your DESCRIPTION file (you may have several vignette builders listed there, and mix static and dynamic vignettes).