Package 'newsfeed'

Compile NEWS files from several packages

Description

This package will take the first chunk of a NEWS file and return it as a character vector. Users should call this function within a folder *above* all of the packages in the 'packages' argument. This will ensure that the proper NEWS path is obtained.

Usage

collect(
  packages,
  vpattern = "Changes in version",
  render = TRUE,
  rawHTML = FALSE
)

Arguments

packages	character() A vector of packages with NEWS files
vpattern	character(1) The 'grep' input for searching the versioning line in the NEWS files. This usually starts with 'Changes in version' but may differ.
render	logical(1) Whether to produce an HTML document for viewing (default: TRUE)
rawHTML	logical(1) Whether to return the raw HTML text when 'render = TRUE' (default: FALSE)

Details

The NEWS file location can be in one of four locations relative to the package directory:

• "NEWS.md"

• "NEWS"

• "inst/NEWS"

• "inst/NEWS.md"

• "inst/NEWS.Rd"

Obtained from Bioconductor NEWS guidelines: https://www.bioconductor.org/developers/package-guidelines/#news

Examples

collect("newsfeed")
## Not run: 
    pkgs <- c(
        "MultiAssayExperiment", "curatedTCGAData", "TCGAutils",
        "cBioPortalData", "SingleCellMultiModal", "RTCGAToolbox",
        "RaggedExperiment", "terraTCGAdata", "BiocBaseUtils", "TENxIO",
        "BiocHubsShiny"
    )
    stopifnot(all(dir.exists(pkgs)))
    collect(pkgs)

## End(Not run)

---

Obtain only the top part of the NEWS file

Description

This function is used internally for collating the latest NEWS after validation with the 'validate' function.

Usage

extract(pkg, vpattern = "Changes in version")

Arguments

vpattern

character(1) The 'grep' input for searching the versioning line in the NEWS files. This usually starts with 'Changes in version' but may differ.

---

Utilities for manipulating NEWS.md headers

Description

We provide several utilties for working with Markdown-style NEWS.md files. Such operations include the manipulation of NEWS.md file headers and header case.

Usage

pkgHeadings(packages, vpattern = "Changes in version")

Arguments

packages	character() A vector of package names that correspond to folders in the current directory.
vpattern	character(1) The 'grep' input for searching the versioning line in the NEWS files. This usually starts with 'Changes in version' (default) but may differ.
pkg	character(1) The name of a local package whose folder is in in the current working directory.
dry.run	logical(1) Whether to print changes to the console (TRUE) or change the actual NEWS file in the package.
bumpHeaders	logical(1) Whether to increase all markdown headers by one (usually '##' to '###'; default TRUE)
from	character(1) The Markdown header to identify in the NEWS.md file (default '#' aka HTML tag 'h1')
to	character(1) The Markdown header to replace in the NEWS.md file (default '##' aka HTML tag 'h2')

Headings

Obtain the NEWS file Markdown headings ('##') for a list of packages with pkgHeadings which calls headingsFormat recursively. It is useful to see whether there is consistency in the headings corresponding to the 'Changes in version' line in the NEWS.md file

headerCase uses the vpattern input to replace any differently formatted NEWS.md heading, e.g. ⁠CHANGES IN VERSION⁠ to ⁠Changes in version⁠ where the differences are by case only.

updateHeading Increases the Markdown HTML h1 tags to h2 tags with the option (bumpHeaders = TRUE) to bump all the headers for the remaining sub-headers in order to maintain hierarchy, e.g., h2 to h3.

Examples

## Not run: 
    pkgHeadings(
        c("MultiAssayExperiment", "curatedTCGAData", "TCGAutils",
        "cBioPortalData", "SingleCellMultiModal", "RTCGAToolbox",
        "RaggedExperiment")
    )

    headingsFormat("curatedTCGAData", "Changes in version")

    headerCase("RTCGAToolbox")

    updateHeading("cBioPortalData")

## End(Not run)

---

Convert a NEWS file to work with pkgdown

Description

This function will take an existing NEWS.md file and convert it to pkgdown readable format. The former format should have headings that begin with

• CHANGES for 'CHANGES IN VERSION'

• 'New' for 'New features'

• 'Bug' for 'Bug fixes and minor improvements'

These headings usually begin with 'h2' headers or double hashtag. An n-1 operation is performed on these headings (if the heading had two hashtags 'h2', they are now converted to one hashtag 'h1').

Usage

reformat(pkg = ".", backup = ".bak")

Arguments

pkg	character(1) The directory location of the package usually the current directory (default: ".")
backup	character(1) The file extension to add for backing up the original news file (default: '.bak')

Value

Saves a "NEWS.md" file with alternative format

---

Change the NEWS.md file headings

Description

Some 'NEWS.md' files have the package name in the heading. This is not yet supported in the 'collect' code. This convenience function will help the user modify those headings to exclude the package name and include the keywords 'Changes in version' for aggregating news files across packages. Version control of the NEWS files is highly recommended. By default, the function saves a '*.bak' backup NEWS file in the package directory.

Usage

rename(pkg, backup = ".bak", dry.run = TRUE)

Arguments

pkg	character(1) The directory location of the package usually the current directory (default: ".")
backup	character(1) The file extension to add for backing up the original news file (default: '.bak')

Value

Saves a "NEWS.md" file with substituted headers

Examples

# create phony DESC for usethis
# otherwise temp 'package' is not recognized
desc <- usethis:::build_description(
    basename(tempdir()), roxygen = TRUE, fields = list()
)
lines <- desc$str(by_field = TRUE, normalize = FALSE, mode = "file")
usethis:::write_over(
    file.path(tempdir(), "DESCRIPTION"), lines, quiet = TRUE
)

tempNews <- file.path(tempdir(), "NEWS.md")
writeLines("# TempPackage 0.99.0", con = file(tempNews))
rename(pkg = tempdir())
readLines(tempNews)

---

Create a NEWS.md file from NEWS file

Description

This function will add a package name line to the current NEWS file and write a NEWS.md file for viewing on GitHub. Future iterations will simplify formatting changes to the NEWS file so that it can be converted to a markdown file. Current files should have markdown syntax in the NEWS file.

Usage

translate(pkg = ".", overwrite = FALSE)

Arguments

pkg	character(1) The directory location of the package usually the current directory (default: ".")
overwite	logical(1) Whether to overwrite the existing NEWS.md file (default: FALSE)

Value

Saves a file with the name "NEWS.md" in the package directory

---

Check that NEWS and DESCRIPTION package versions are correct

Description

The NEWS file contains version information that can be parsed and checked against the package version in the DESCRIPTION file.

Usage

validate(pkg, vpattern = "Changes in version")

Arguments

vpattern

character(1) The 'grep' input for searching the versioning line in the NEWS files. This usually starts with 'Changes in version' but may differ.

Examples

## Not run: 
validate("MultiAssayExperiment")
validate("RaggedExperiment")

## End(Not run)

---