Bookdown Conversion Notes and TODO

[dylanbeaudette]

Andrew's notes, originally from #23:

I redid the S4SS Part 1 book in bookdown.

http://ncss-tech.github.io/stats_for_soil_survey/book/

I am not an expert on bookdown at all -- but I have done several small projects. This is my most complex yet.

This is a great resource, from the master himself: https://bookdown.org/yihui/bookdown/

Many aspects of the gitbook/bookdown workflow can be enhanced using the Rstudio Addin for {bookdown} -- so you should probably get familiar with that if you want to build the book yourself. I would suggest trying your own sample RStudio bookdown Project template. Both addin and template available if you have the package installed.

## get bookdown
install.packages('bookdown')

Non-CRAN Dependency

remotes::install_github('r-spatial/mapview')

For a missing html_dependency (CSS files) need mapview >2.9.0 or the interactive plots will not render in bookdown. Note they work fine in regular sessions -- this is only required if you want to build book and have interactive maps work.

Build the book

To build the book, this is the basic sequence of commands.

options(bookdown.clean_book = TRUE)

# remove ../book and other intermediate build files
bookdown::clean_book()

# create ../book where . is the _source_ directory of the book (i.e. /newbook, not /book)
bookdown::render_book(".")

Fancy stuff

In RStudio, there is an addin to use bookdown::serve_book() -- which is really nice and can incorporate a lot of your changes dynamically on the fly. It gets hairy if you edit multiple chapters at once, or start editing the live code chunks. If things get hung up you have to restart your Rstudio session, and if it crashes or gives really strange errors not related to code maybe clean_book as above.

Data requirements

Currently all the examples do not require any specific selected set contents or set up on users computer -- aside having the datasets downloaded from chapter 4 spatial examples, formerly Chapter 2b (which is eval=FALSE to make the book build faster/better). So run that chunk independently to download the ZIP files before you try to build the book. There are several ways I could possibly "optimize" book build time but I have struck a balance of reproducibility/complexity/build time and time-time.

Open to edits and suggestions

Anyone can edit the course book .Rmd files. You do not have to re-build the book, or commit changes that you make to the "published" HTML book. I think that building the whole book, regularly, is essential for multiple collaborators/reproducibility of the book contents.

Caution/encouragement on building the book

I would gladly take on the role of building the book and fixing errors that arise from anyone who does not feel confident building it themselves. It is not the most trivial thing, but I think it is the way forward. I sort of sprung it on you all as a way of wrangling the diverse and complex existing content. Please contact me and we can discuss fastest most effective way to incorporate your suggestions.

You want to be careful when it comes to adding code chunks. All code chunks are eval=FALSE unless explicitly set to true. With false it is safe, they will show up as code blocks and will not be executed by the R interpreter unless you "flip the switch." With TRUE, you could in theory "break" the whole book until the error in your code is resolved.

It might be best to work in a branch if you have significant changes -- that way I or others can help. The ultimate saving grace is that an un-built book will not overwrite the HTML -- and bad HTML won't overwrite the book if you do not commit it -- so the live book remains intact.

[dylanbeaudette]

Thanks @brownag. Using these notes, and some tinkering with the contents of /newbook I've parked a first edition of Part 2 "book" content in /Part2, with output stored in /book2.

http://ncss-tech.github.io/stats_for_soil_survey/book2/

Questions for the group:

• Keeping Parts 1 and 2 split helps to keep the book-building process simpler, and the TOC more manageable. I vote to keep them split and maybe re-organized into folders with connotative names. Thoughts?

Notes:

• don't forget to set eval = TRUE in all code blocks that need to be run
• I figured out a simple way to shrink the source code and code results, see style.css. There is some CSS magic going on that overrides some settings such as borders and fancy decorations.

TODO:

• I do think that we should re-design the pre-class assignment (a little) for Part 2.
• Why is the "References" section repeated 2 times?
• setup a registry of all data that need to be in-place for the book to compile, and code to put it in place if needed
• labeling chunks might cut down on the image churn in the repository
• use figure captions when appropriate

Front matter or colophon.

There should be a short preface to the "books" that set the stage, along with some information on versions of critical packages.

This document is based on `aqp` version `r utils::packageDescription("aqp", field="Version")`, `soilDB` version `r utils::packageDescription("soilDB", field="Version")`, and `sharpshootR` version `r utils::packageDescription("sharpshootR", field="Version")