documentation.Rmd

# Documentation {#docs}

Package documentation is important for users to understand how to work with your code.

## Bioconductor documentation minimal requirements: {#doc-require}

* a [vignette][CRAN vigs] in Rmd or Rnw format with executable code that
  demonstrates how to use the package to accomplish a task,

* [man pages][CRAN Rd] for all exported functions with runnable examples, well
  documented data structures especially if not a [pre-exiting
  class][bioc-common]

* well documented datasets for data provided in `data/` and in `inst/extdata/`.

References to the methods used as well as to other similar or related projects
and packages is also expected.

If data structures differ from similar packages, [_Bioconductor_
reviewers][reviewer-list] will expect some justification as to why. Keep in mind
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 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
  $\LaTeX$ for structuring text sections and resulting in HTML output. The
  `r BiocStyle::CRANpkg("knitr")` package can process most *Sweave* and all *R
  markdown* vignettes, producing pleasing output. Refer to [Writing package
  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.
  
* 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. 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>
session. It is therefore **essential** that the vignette embed executed <i
class="fab fa-r-project"></i> code. Shortcuts (e.g., using a $\LaTeX$ verbatim
environment, or using the *Sweave* `eval=FALSE` flag, or equivalent tricks in
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, 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.

### RMarkdown vignettes

We encourage the use of `r BiocStyle::Biocpkg("BiocStyle")` with the
`html_document` 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
the order that they are displayed on the package homepage and when the
`browseVignettes()` function is called. Vignettes will show up in
alphabetical order, which may not be a logical ordering without
further specification. One approach to controlling the order of the
vignettes is to use a number in the `VignettteIndexEntry` setting,
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: An Introduction}
  %\VignetteEncoding{UTF-8}
```

### Quarto vignettes

More recently, `quarto` vignettes have been introduced as a new format for
vignettes. Quarto vignettes are similar to R Markdown but offer more advanced
features, flexibility, and multi-language support. The yaml front matter for a
Quarto vignette is similar to R Markdown, but it uses `quarto::html` as the
rendering function. For example, in a Quarto vignette one can use the following
specification in the yaml front matter:

```yaml
vignette: >
  %\VignetteEngine{quarto::html}
  %\VignetteIndexEntry{1. Quick Start: An Introduction}
  %\VignetteEncoding{UTF-8}
```

In addition to the yaml front matter, vignette authors must ensure that the
`quarto` command line tool is listed as a `SystemRequirements` in the
`DESCRIPTION` file, as well as, indicate that the `VignetteBuilder` is set to
`quarto` in the `DESCRIPTION` file:

```r
VignetteBuilder: quarto
```

Some best practices and requirements for writing _Bioconductor_ vignettes are
detailed in the following sections.

### Introduction {#vignette-introduction}

Add an "Introduction" section that serves as an abstract to introduce the
objective, models, unique functions, key points, etc that distinguish the
package from other packages in the same area. This is a requirement of
Bioconductor package vignettes. It should include a short motivation for the
package in general as well as motivation for inclusion of the package in
Biconductor. When relevant, a brief review and comparison of packages with
similar functionality or scope should be provided either in the Introduction or
in a separate dedicated vignette section.

### Installation

Add an "Installation" section that show to users how to download and load the
package from Bioconductor.

These instructions and any installations instructions should be in an
`eval=FALSE` code chunk. Nowhere in the code (<i class="fab fa-r-project"></i>
code, man pages, vignettes, Rmd files) should someone try to install or download
system dependencies, applications, packages, etc. Developers can provide
instructions to follow in unevaluated code chunks, and should assume all
necessary dependencies, applications or packages are already set up on a user's
system.

### Table of contents

If appropriate, we strongly encourage a table of contents

### Evaluated code chunks

Non-trivial executable code is a must!!!

Static vignettes are not acceptable.

### Session information

Include a section with the `SessionInfo()` at the end of the vignette.

### `vignettes/` directory and intermediate files

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

Remember to include any relevant references to methods.

## Man pages {#man-pages}

See the [Writing R Extensions section on man pages][CRAN Rd] for detailed
instruction or format information for documenting a package, functions, classes,
and data sets.

All help pages should be comprehensive.

### Package-level documentation

[_Bioconductor_][] encourages having a package man page with an overview of the
package and links to the main functions. Users should be able to have a relevant
page display with `?<package name>`

### Functions and classes

All exported functions and classes need will have a man page. Man pages
describing new classes must be very detailed on the structure and the type of
information that is stored.

### Data {#data-man}

Data man pages must include provenance information and data structure information.

### Examples

All man pages should have an runnable examples.

The use of `donttest` and `dontrun` is discouraged and generally not allowed;
exceptions can be made with proper justification and are at the discretion of
[_Bioconductor_ reviewers][reviewer-list].

If this option is used it will also be preferable to use `donttest` instead of
`dontrun`; `donttest` requires valid <i class="fab fa-r-project"></i> code while
`dontrun` does not.

## The `inst/scripts/` directory {#doc-inst-scripts}

The scripts in this directory can vary.

Most importantly if data was included in the `inst/extdata/` directory, a
related script must be present in this directory clearly documenting how the
data was obtained and prepared.

It should include any source URLs and information regarding filtering or
pre-processing.

It can be executable code, sudo code, or even a text description.

Users should be able to download and roughly reproduce the data file or object
in `inst/extdata/`.

## The `data-raw` directory {#doc-data-raw}

Although the preferred location is `inst/scripts`, the `data-raw` directory may
be used instead to store scripts that generated data files or objects. Note
that one potential disadvantage of using the `data-raw` directory is that the
scripts are not included in the package installation folder (for users to
inspect).

For more details, see the `Data` chapter in Hadley Wickham's
[R Packages][r-pkgs].

[r-pkgs]: https://r-pkgs.org/data.html

## Other {#other-doc}

Other types of documentation (e.g. static files, jupyter notebooks, etc.) can be
provided through `inst` subdirectories but do not substitute for the
[_Bioconductor_ documentation requirements](#doc-require) listed above.