Merge branch 'devel' into update_build_deploy

Author: lshep

README.md

@@ -13,7 +13,7 @@ Bioconductor Packages: Guidelines for Developers and Reviewers
 
 This book contains our guidelines for packages contributed to the [_Bioconductor_](https://bioconductor.org/) suite of packages.
 These guidelines are always a work in progress - corrections, suggestions and general improvements are welcome as [issue submissions in this repository](https://github.com/Bioconductor/pkgrevdocs/issues/new).
-Open discussions are welcome in our [Slack](https://bioc-community.herokuapp.com/).
+Open discussions are welcome in our [Zulip](https://community-bioc.zulipchat.com/).
 You can also suggest changes by editing the `.Rmd` files that are at the root of this repository and submitting a [pull request](https://github.com/Bioconductor/pkgrevdocs/pulls).
 An "Edit this page" link in the side bar on the right of each book chapter will take you directly to the relevant page on the GitHub repository to make such changes.
 Please target your pull requests to the `devel` branch.

_bookdown.yml

@@ -44,5 +44,6 @@ rmd_files: ["index.Rmd",
            "c-and-fortran.Rmd",
            "mavericks.Rmd",
            "debug-rd-links.Rmd",
-           "news-for-bookdown.Rmd"]
+           "news-for-bookdown.Rmd",
+           "references.Rmd"]
 clean: [packages.bib]

debug-rd-links.Rmd

@@ -27,7 +27,7 @@ W  checking Rd cross-references (<...>ms)
 ## What worked
 
 First, the `SummarizedExperiment` package was added to the `Depends:` section
-of the DESCRIPTION file.
+of the `DESCRIPTION` file.
 
 ```
 Depends:

description-file.Rmd

@@ -192,7 +192,7 @@ package type (i.e., `Software`, `AnnotationData`, `ExperimentData`, or
 `Workflow`). `biocViews` terms are case-sensitive.
 
 The field name "biocViews" is case-sensitive and must begin with a lower-case
-'b'. Please use a single line with biocViews seperated by commas
+'b'. Please use a single line with `biocViews` separated by commas
 
 (i.e,`biocViews: GeneTarget, SingleCell`).
 

documentation.Rmd

@@ -24,7 +24,7 @@ it is always possible to extend existing classes.
 ## Vignettes {#vignettes}
 
 A vignette demonstrates how to accomplish non-trivial tasks embodying the core
-functionality of your package. There are two common types of vignettes.
+functionality of your package. There are three types of vignettes.
 
 * (Recommended) An *R markdown* vignette is similar to a *Sweave* vignette, but
   uses [markdown](http://daringfireball.net/projects/markdown/) instead of
@@ -34,11 +34,20 @@ functionality of your package. There are two common types of vignettes.
   vignettes][CRAN vigs] for technical details. See the
   `r BiocStyle::Biocpkg("BiocStyle")` package for a convenient way to use common
   macros and a standard _Bioconductor_ style vignette.
-
-* A *Sweave* vignette is an `.Rnw` file that contains $\LaTeX$ and chunks of <i
-  class="fab fa-r-project"></i> code. The  code chunk starts with a line
+  
+* Quarto is a new format for vignettes that uses the
+  [Quarto](https://quarto.org/) system. It is similar to R Markdown but offers
+  more advanced features and flexibility. Similar to R Markdown, Quarto
+  vignettes can be rendered to various formats, including HTML and PDF, and are
+  suitable for multi-language documentation needs. Note that an installation
+  of the `quarto` command line tool is required to build Quarto vignettes.
+
+* A *Sweave* vignette is an `.Rnw` file that contains $\LaTeX$ and chunks of
+  <i class="fab fa-r-project"></i> code. The  code chunk starts with a line
   `<<>>=`, and ends with `@`. Each chunk is evaluated during `R CMD build`,
-  prior to $\LaTeX$ compilation to a PDF document.
+  prior to $\LaTeX$ compilation to a PDF document. Note that this format
+  requires $\LaTeX$ dependencies for rendering that are not be available in
+  standard _Bioconductor_ containers.
 
 A vignette provides reproducibility: the vignette produces the same results as
 copying the corresponding commands into an <i class="fab fa-r-project"></i>
@@ -49,21 +58,20 @@ markdown) undermine the benefit of vignettes and are generally **not allowed**;
 exceptions can be made with proper justification and are at the discretion of
 [_Bioconductor_ reviewers][reviewer-list].
 
-All packages are required to have at least one Rmd or Rnw vignette. Vignettes go
-in the `vignettes/` directory of the package. Vignettes are often used as
-standalone documents, so best practices are to include an informative title, the
-primary author of the vignette, the last modification date of the vignette, and
-a link to the package landing page. We encourage the use of `r
-BiocStyle::Biocpkg("BiocStyle")` for formatting with `html_document` as
-rendering target. Something like the following in the vignette will accomplish
-the above suggestion:
+All packages are required to have at least one Rmd, qmd, or Rnw vignette.
+Vignettes go in the `vignettes/` directory of the package. Vignettes are often
+used as standalone documents, so best practices are to include an informative
+title, the primary author of the vignette, the last modification date of the
+vignette, and a link to the package landing page. We encourage the use of
+`r BiocStyle::Biocpkg("BiocStyle")` with `html_document` as the rendering
+function. For example, in an R Markdown vignette one can use the following
+specification in the yaml front matter:
 
-```
+```yaml
 output:
   BiocStyle::html_document:
     toc: true
     toc_depth: 2
-
 ```
 
 If you want to write more than one vignette, you may want to control
@@ -76,10 +84,10 @@ e.g. using numbers `1-9`, if you have a single digit number of
 vignettes, or `01-99` if you have ten or more vignettes. For example,
 the first vignette could specify in the header:
 
-```
+```yaml
 vignette: >
   %\VignetteEngine{knitr::rmarkdown}
-  %\VignetteIndexEntry{1. Quick start to MyPackage}
+  %\VignetteIndexEntry{1. Quick Start: An Introduction}
   %\VignetteEncoding{UTF-8}
 ```
 
@@ -126,12 +134,11 @@ Include a section with the `SessionInfo()` at the end of the vignette.
 
 ### `vignettes/` directory and intermediate files
 
-Only the source vignette file (`.Rnw` or `.Rmd`) and any necessary static images
-should be in the vignette directory. No intermediate files should be
-present. This include complete processed vignette products as well; the vignette
-should be created through the `R CMD build` of a package. To include other types
-of documentation please use the `inst/doc` or other appropriately named `inst`
-directory.
+Only the source vignette file (`.Rnw`, `.qmd`, or `.Rmd`) and any necessary
+static images should be in the `vignettes/` directory. No intermediate files
+should be present, including vignette products. Vignettes are created through
+by running `R CMD build` on a package. To include other types of documentation
+please use the `inst/doc` or other appropriately named `inst` directory.
 
 ### References
 

general-package-development.Rmd

@@ -42,8 +42,12 @@ Do not use filenames that differ only in case, as not all file systems are case-
 
 ### Package size {#package-size}
 
-The source package resulting from running `R CMD build` should occupy less than 5 MB on disk.
-If your package includes (e.g. in the vignettes) some screenshots, this limit can be reached quite quickly. Their size can be reduced (often as much as 70%) in a lossy but quality-preserving manner by using tools such as [pngquant](https://pngquant.org/) (available as a command line utility and as a GUI on most systems).
+The source package resulting from running `R CMD build` should occupy less than
+5 MB on disk. If your package includes some screenshots (e.g., in the
+vignettes), this limit can be reached quite quickly. Their size can be reduced
+(often as much as 70%) with lossy compression using tools such as
+[pngquant](https://pngquant.org/) (available as a command line utility and as a
+GUI on most systems).
 
 ### Check duration {#check-duration}
 

git-version-control.Rmd

@@ -79,19 +79,20 @@ Builds occur once per day, and take approximately 24 hours. See the
 
 Traditional Annotation packages are not stored in GIT due to the size of
 annotation files. To update an existing Annotation package please send an email
-to [email protected]. A member of the Bioconductor team will be in
+to <[email protected]>. A member of the Bioconductor team will be in
 contact to receive the updated package.
 
 Newer annotation packages can be stored in GIT as it is a requirement to use the
 `r BiocStyle::Biocpkg("AnnotationHub")` server hosted data. The larger sized
 files are not included directly in the package. To contribute a new Annotation
-package please contact [email protected] for guidance and read the
+package please contact <[email protected]> for guidance and read the
 documentation on [Create A Hub Package][].
 
 Currently direct updates to annotation packages, even those stored on git, are
 not supported. If you wish to updated an annotation package, make required
 changes and push to git.bioconductor.org. Then send an email to
-[email protected] or [email protected] requesting the package be propagated.
+<[email protected]> or <[email protected]> requesting the package
+be propagated.
 
 ## Subversion to Git Transition
 
@@ -704,7 +705,7 @@ _Bioconductor_ repositories.
 
 __Goal:__ You want to start fresh after failing to resolve conflicts
 or some other issue. If you intend to go nuclear, please contact the
-[email protected] mailing list.
+<[email protected]> mailing list.
 
 #### Force _Bioconductor_ `devel` to GitHub `devel`
 
@@ -1058,9 +1059,9 @@ maintain the package and avoid deprecation and removal.
    package be updated.  Include the package name and the contact information for
    the new maintainer.
 
-3. Update Package DESCRIPTION file
+3. Update Package `DESCRIPTION` file
 
-   The DESCRIPTION file of the package should be updated to the new maintainer
+   The `DESCRIPTION` file of the package should be updated to the new maintainer
    information and pushed to the Bioconductor git.bioconductor.org repository.
 
 ### Remove Large Data Files and Clean Git Tree
@@ -1435,7 +1436,7 @@ repository.
 #### More questions?
 
 If you have additional questions which are not answered here already,
-please send an email to [email protected].
+please send an email to <[email protected]>.
 
 ### Helpful resources:
 

important-bioc-features.Rmd

@@ -3,10 +3,10 @@
 ## biocViews {#biocviews}
 
 Packages added to the _Bioconductor_ Project require a `biocViews:`
-field in their DESCRIPTION file.  The field name "biocViews" is
+field in their `DESCRIPTION` file.  The field name "biocViews" is
 case-sensitive and must begin with a lower-case 'b'.
 
-biocViews terms are "keywords" used to describe a given package. They
+`biocViews` terms are "keywords" used to describe a given package. They
 are broadly divided into four categories, representing the type of
 packages present in the _Bioconductor_ Project 
 
@@ -15,29 +15,29 @@ packages present in the _Bioconductor_ Project
 3. Experiment Data
 4. Workflow
 
-biocViews are available for the [release][release-biocviews] and [devel][biocViews] branches of
-_Bioconductor_. The devel branch has a check box under the tree
-structure which, when checked, displays biocViews that are defined but
-not used by any package, in addition to biocViews that are in use. See also
-[description section](#description-biocviews)
+`biocViews` are available for the [release][release-biocviews] and
+[devel][biocViews] branches of _Bioconductor_. The devel branch has a check box
+under the tree structure which, when checked, displays `biocViews` that are
+defined but not used by any package, in addition to `biocViews` that are in use.
+See also [description section](#description-biocviews)
 
 ### Motivation {#biocviews-motivation}
 
-One can use biocViews for two broad purposes.
+One can use `biocViews` for two broad purposes.
 
 1. A researcher might want to identify all packages in the
    _Bioconductor_ Project which are related to a specific purpose.
    For example, one may want to look for all packages related to "Copy
    Number Variants".
 
 2. During development, a package contributor can "tag" their package
-   with biocViews so that when someone looking for packages (like in
+   with `biocViews` so that when someone looking for packages (like in
    scenario 1) can easily find their package.
 
 ### biocViews during new package development {#biocviews-pkg-devel}
 
 Visit the ['devel' biocViews][biocViews] when you are in the process of
-adding biocViews to your new package. Identify as many terms as
+adding `biocViews` to your new package. Identify as many terms as
 appropriate from the hierarchy. Prefer 'leaf' terms at the end of the
 hierarchy, over more inclusive terms. Remember to check the box
 displaying all available terms.
@@ -46,30 +46,30 @@ Please Note:
 
 1. Your package will belong to only one part of _Bioconductor_ Project
    (Software, Annotation Data, Experiment Data, Workflow), so choose only
-   biocViews from that category.
+   `biocViews` from that category.
 
-2. biocViews listed in your package must match exactly (e.g.,
-   spelling, capitalization) the terms in the biocViews hierarchy.
+2. `biocViews` listed in your package must match exactly (e.g.,
+   spelling, capitalization) the terms in the `biocViews` hierarchy.
 
 When you submit your new package for review , your package is checked
 and built by the _Bioconductor_ Project.  We check the following for
 biocViews:
 
-1. Package contributor has added biocViews.
+1. Package contributor has added `biocViews`.
 
-2. biocViews are valid.
+2. `biocViews` are valid.
 
-3. Package contributor has added biocViews from only one of the categories.
+3. Package contributor has added `biocViews` from only one of the categories.
 
-If you receive a "RECOMMENDED" direction for any of these biocViews
+If you receive a "RECOMMENDED" direction for any of these `biocViews`
 after you have submitted your package, you can try correcting them on
 your own following the directions given here or ask your package
 reviewer for more information.
 
-If a developer thinks a biocViews term should be added to the current acceptable
-list, please email [email protected] requesting the new biocView, under
-which hierarchy the term should be placed, and the justification for the new
-term.
+If a developer thinks a `biocViews` term should be added to the current
+acceptable list, please email <[email protected]> requesting the new
+`biocViews` term, under which hierarchy the term should be placed, and the
+justification for the new term.
 
 
 ## Common Bioconductor Methods and Classes {#reusebioc}

index.Rmd

@@ -5,6 +5,8 @@ author:
   - Daniela Cassol
   - Johannes Rainer
   - Lori Shepherd
+  - Marcel Ramos Pérez
+  - Martin Morgan
 date: "`r Sys.Date()`"
 site: bookdown::bookdown_site
 documentclass: book
@@ -17,7 +19,7 @@ description: "This is a minimal example of using the bookdown package to write a
 # Welcome {-}
 
 ```{r, fig.align='center', echo=FALSE, out.height="200px"}
-knitr::include_graphics("https://raw.githubusercontent.com/Bioconductor/BiocStickers/master/Bioconductor/Bioconductor.png")
+knitr::include_graphics("https://raw.githubusercontent.com/Bioconductor/BiocStickers/devel/Bioconductor/Bioconductor.png")
 ```
 
 ## Introduction {.unnumbered #intro}
@@ -132,7 +134,7 @@ knitr::write_bib(c(
 [Removing collaborator]: https://help.github.com/articles/removing-a-collaborator-from-a-personal-repository/
 [Resolving a merge conflict using command line]: https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
 [reviewer-list]: https://bioconductor.org/about/package-reviewers/
-[reviewers slack channel]: https://community-bioc.slack.com/archives/C02A1B8HUHZ
+[reviewers zulip channel]: https://community-bioc.zulipchat.com/#narrow/channel/507978-reviewers
 [rmarkdown]: http://rmarkdown.rstudio.com/
 [rmarkdown documentation]: http://rmarkdown.rstudio.com/authoring_pandoc_markdown.html#citations
 [shiny-posit]: https://shiny.posit.co/

install-file.Rmd

@@ -11,7 +11,7 @@ already there.
 
 Specifying this requirement does not guarantee that _Bioconductor_ will agree to
 install the external system requirement. It is encouraged to discuss any
-additional system requirements on the [email protected] before
+additional system requirements on the <[email protected]> before
 development.
 
 System requirements should never be exclusive to a particular