Turning a book into an R package about bookdown

[yihui]

Yep, it is a nice idea to create books from vignettes. This idea has been on my mind for a couple of years, e.g. https://dl.dropboxusercontent.com/u/15335397/slides/FHCRC-VTN-2013-Yihui-Xie.html#/20 An R package is basically a small well-structured universe.

I think it is possible and easy to come up with a vignette engine to render Rmd vignettes as a book, but we will need some support from base R. For example, R CMD build should not clean up any output files of the book (currently it does clean up everything except the single html output file).

Or we just do not use vignettes, but put the book in a different directory, e.g. inst/book/, and build the book during R CMD build (it is easy to find a spot to trigger the build). The only problem is this is not as discoverable as vignettes in the package, but I think this issue is trivial. We could definitely provide some helper functions that behave like vignette() to show the book.

[yihui]

1. To be honest, I use serve_book() myself when I write a book, so there is no need to click a button.
2. Not an issue. You can do anything you want with a shell script. It does not matter whether the project is an R package or a book, or where the book directory is.

I don't really see huge benefits of incorporating a book into the vignette system of an R package. I think it is possible, though. One idea is you put the book source files elsewhere (anywhere except the root directory vignettes/), e.g. a subdirectory of vignettes/: vignettes/my-book/[index.Rmd|chap1.Rmd|...]. Then you use a placeholder Rmd vignette vignettes/foo.Rmd to build the book under vignettes/my-book/ (do this in a code chunk in foo.Rmd; just call bookdown::render_book() with appropriate settings). After the book is built, copy the output back to vignettes/. You will need vignettes/.install_extras to make sure R does not wipe out the book output: https://cran.rstudio.com/doc/manuals/r-release/R-exts.html#Writing-package-vignettes This is essentially a hack, but I think it is a feasible way to go, if you want to pursue the idea of building a book inside a package.

[maxheld83]

interesting idea.
I was thinking the other day that it would be inelegant to have both vignettes (maintained with the package) and some book about an R package.

On the other hand, this dual role could make things more complicated.

[maxheld83]

I'm still thinking about this, and I noticed that this very project bookdown actually is both a book and a package, as @yihui also mentioned in #215

I'd be curious to hear some more guidance and/or experiences with this.
Would you recommend this for other package/book combinations and/or be willing to add this to the bookdowndocumentation @yihui ?

I gather the following shortcomings / complications should be borne in mind:

1. RStudio build will only be able to build one of the two (package or book), though serving via serve_book() might be a good way to continuously build the docs, while continuing to build the package via RStudio buttons.
2. Travis (or other) CI might need a slightly more complicated shell script, though I can't see why it couldn't first build a package, and then render a book. Or could that be an issue?
3. ... anything else I missed?

I'm also still wondering whether, say, the (K+Med) book chapters might also be vignettes in and of themselves.

Uh, I don't know, sometimes I make things too complicated for myself, I'd just really appreciate some guidance/experience from @yihui if you have the time for some comment.

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.