Conversion to BiocBook

[js2264]

Hi @lgatto and colleagues, I had the opportunity to discuss with you during the EuroBioc23 conf. I've been working on adapting your great book to the BiocBook infrastructure. If you are interested in accepting this PR, let me know and we can discuss in more detail to make sure things run ok.

Few points worth bringing up:

• The pages are now in qmd (quarto) format, and located in inst/index.qmd and inst/pages/*qmd. You can add any page to the book by creating a new .qmd file in inst/pages/ and reference this file in the inst/assets/_book.yml listing.
• I have copied and pasted most of the pages content, and made very minor changes (such as wrapping the question/answer parts in a specific callout, rather than using msmbstyle). This should allow pdf rendering (the rendering was crashing with the msmbstyle tags).
• This PR should actually be merged to a new devel branch on the rformassspectrometry/book repo, not the base I currently selected (but I cannot directly create this branch in your repo). This would allow automatic detection of the Bioc version to use: a branch named devel (or RELEASE_3_18) will use bioc devel (or bioc 3.18) to build the book (and deploy it to gh-pages:docs/3.18). The main branch is not going to trigger automated book building at all.
• If you want to serve the book from the github repository, the Pages settings should be set to serve Pages from the gh-pages branch (root folder). An automated redirection sends to gh-pages:docs/devel, but can be set up to other versions (if any RELEASE_* branch exists). The URL that points to an actual book would be https://.github.io//docs/devel/ (or https://.github.io//docs/RELEASE_*/).
• The repo can be installed with remotes::install_github("js2264/R4MS"), which sets up all the dependencies from CRAN/Bioc. Alternatively, a docker image with pre-configured RStudio server is available ("docker pull ghcr.io/js2264/r4ms:devel"). Once the PR pulled, this would become rformassspectrometry/book of course.
• This leads me to the following personal comment, that rformassspectrometry/book is not very informative, and notably is in conflict with the conventions for Bioconductor package submissions (which state that the package repository should have the same name as the package itself). If you intend to submit this book as a BiocBook package to Bioconductor, you'd have to consider renaming the repository or the package.

Let me know if there is anything unclear!

[lgatto]

This looks great, thank you very much for this @js2264 and sorry for not getting back to you in time. I will take time by the end of the year and get back to you.

[lgatto]

This leads me to the following personal comment, that rformassspectrometry/book is not very informative, and notably is in conflict with the conventions for Bioconductor package submissions (which state that the package repository should have the same name as the package itself). If you intend to submit this book as a BiocBook package to Bioconductor, you'd have to consider renaming the repository or the package.

This is a good point, indeed. But the book is foremost part of the R for Mass Spectrometry initiative, and the repo name book makes most sense here. I suppose we could rename the repo RforMassSpectrometryBook, to fit the Bioconductor package name requirement, event though I can see two issues:

• we have been using the link that URL for some time (I know Github does redirection, but we already redirect from github.com/Rformassspectrometry/docs :-/ ) and
• github.com/rformassspectrometry/RforMassSpectrometryBook is overly long and confusing

I am also wondering to what extend the naming rule should be applied as is in the context of books.

[js2264]

This leads me to the following personal comment, that rformassspectrometry/book is not very informative, and notably is in conflict with the conventions for Bioconductor package submissions (which state that the package repository should have the same name as the package itself). If you intend to submit this book as a BiocBook package to Bioconductor, you'd have to consider renaming the repository or the package.

This is a good point, indeed. But the book is foremost part of the R for Mass Spectrometry initiative, and the repo name book makes most sense here. I suppose we could rename the repo RforMassSpectrometryBook, to fit the Bioconductor package name requirement, event though I can see two issues:

• we have been using the link that URL for some time (I know Github does redirection, but we already redirect from github.com/Rformassspectrometry/docs :-/ ) and
• github.com/rformassspectrometry/RforMassSpectrometryBook is overly long and confusing

I am also wondering to what extend the naming rule should be applied as is in the context of books.

IMO these are valid reasons to keep book as a repo name and choose a separate name for the actual package (in DESCRIPTION). I'm not sure how much this can be negotiated with reviewers during submission, but because this is a book hopefully there can be a little bit of flexiility.

As a remainder:

1. if you intend to submit the package to bioconductor as a book package, a URL pointing to versioned books will be https://bioconductor.org/books/<BIOC_VERSION>/<PACKAGE_NAME>/.
2. Regardless of whether it ends up on BioC, a Docker image is built and available at docker pull ghcr.io/<GITHUB_USER>/<package_name_in_lowercase>:<PACKAGE_VERSION>.

So the package name is quite important, even though it won't be directly installed by end-users.

[lgatto]

@jorainer - what do you think if converting the book to a BiocBook/package? I think we should go for it, merge, as address the (minor) open points as we go.