readme-file.Rmd

# The README file {#readme}

Bioconductor does not require `README` files in packages but they
are often useful for newcomers, especially when a package is developed
on <i class="fab fa-github"></i> GitHub or similar online platforms. 

Bioconductor packages with a `README` file should clearly indicate
[_Bioconductor_][] installation instructions. See the example installation
instructions for `GenomicRanges`:

```r
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("GenomicRanges")
```

As a general rule, files that run <i class="fab fa-r-project"></i> code
(including `README.Rmd`) should not install packages, download system
dependencies, or applications. Installation instructions should be in
an `eval = FALSE` code chunk.

Developers should assume that all necessary dependencies, applications, and
packages are already installed on the user's system.

**Note**. Packages with external software dependencies should use the
`SystemRequirements` field in the `DESCRIPTION` file. See also
[the INSTALL file](#sysdep) for system dependencies requirements.

## Generating the README.md from the main vignette

Optionally, the `README.md` file can be generated from a package's vignette
via the `README.Rmd`. Using the child document feature in R Markdown, the
`README.Rmd` can render a vignette and output a `README.md` file.
Below is an example `README.Rmd` file that renders a vignette (named
`mainVignette.Rmd`).

```r
## ---
## output: github_document
## ---
## 
## ```{r, child="../../vignettes/mainVignette.Rmd"}
## ```
```

The developer can then generate the `README.md` file by running
`rmarkdown::render` as:

```r
rmarkdown::render("inst/scripts/README.Rmd", output_dir = ".")
```