litedown (version 1.0)

pkg_desc: Print the package description, news, citation, manual pages, and source code

Description

Helper functions to retrieve various types of package information that can be put together as the full package documentation like a pkgdown website. These functions can be called inside any R Markdown document.

Usage

pkg_desc(name = detect_pkg(), type = c("table", "dl"))
pkg_news(
  name = detect_pkg(),
  path = detect_news(name),
  recent = 1,
  toc = TRUE,
  number_sections = TRUE,
  ...
)
pkg_code(
  path = attr(detect_pkg(), "path"),
  pattern = "[.](R|c|h|f|cpp)$",
  toc = TRUE,
  number_sections = TRUE,
  link = TRUE
)
pkg_examples(
  path = attr(detect_pkg(), "path"),
  dir = "examples",
  groups = site_groups("examples")
)
pkg_citation(name = detect_pkg())
pkg_manual(
  name = detect_pkg(),
  toc = TRUE,
  number_sections = TRUE,
  overview = TRUE,
  examples = list(),
  groups = site_groups("manual")
)
pkg_articles(name = detect_pkg(), groups = site_groups("articles"))

Value

A character vector (HTML or Markdown) that will be printed as is inside a code chunk of an R Markdown document.

pkg_desc() returns an HTML table containing the package metadata.

pkg_news() returns the news entries.

pkg_code() returns the package source code under the R/ and src/ directories.

pkg_examples() returns a list of boxes for the example files (e.g., .Rmd files) under the examples/ directory of the package, each with a link to its output, a link to its source, and a preview of the source.

pkg_citation() returns the package citation in both the plain-text and BibTeX formats.

pkg_manual() returns all manual pages of the package in HTML.

pkg_articles() returns a list of links to the built vignettes of the package (and their source files) in Markdown. It also copies the doc directory of the installed package to the current directory.

Arguments

name

The package name (by default, it is automatically detected from the DESCRIPTION file if it exists in the current working directory or upper-level directories).

type

The HTML tag for the description: table (<table> with <tr> and <td>) or dl (definition list <dl> with <dt> and <dd>). The dl type generates a compact description for a sidebar (a fenced Div with the classes side and side-right): the fields Description and Suggests are omitted, and the fields URL and BugReports are merged into a field Links, in which URLs are shown as short text links (instead of long bare URLs that cannot be wrapped in a narrow sidebar).

path

For pkg_news(), path to the NEWS.md file. If empty, news() will be called to retrieve the news entries. For pkg_code(), path to the package root directory that contains R/ and/or src/ subdirectories.

recent

The number of recent versions to show. By default, only the latest version's news entries are retrieved. To show the full news, set recent = 0.

toc

Whether to add section headings to the document TOC (when TOC has been enabled for the document).

number_sections

Whether to number section headings (when sections are numbered in the document).

...

Other arguments to be passed to news().

pattern

A regular expression to match filenames that should be treated as source code.

link

Whether to add links on the file paths of source code. By default, if a GitHub repo link is detected from the BugReports field of the package DESCRIPTION, GitHub links will be added to file paths. You can also provide a string template containing the placeholder %s (which will be filled out with the file paths via sprintf()), e.g., https://github.com/yihui/litedown/blob/main/%s.

dir

The directory of examples, relative to the package root path.

groups

A list of groups, each of which is a list with the fields title, desc (optional), and contents, where contents is a character vector of names to be matched (* and ? are wildcards): topic names or Rd filenames for pkg_manual(), vignette filenames or titles for pkg_articles(), and filenames or titles of the example files for pkg_examples(). Items that do not belong to any group are put in a group named Other, except help pages with the keyword internal, which are listed only if a group names them (e.g., re-exported functions). A name that matches nothing is an error. By default, groups are read from the subfield manual, articles, or examples of the field site in _litedown.yml in the current directory, e.g.,

site:
  manual:
    Sites:
      desc: Build package sites
      contents: [pkg_site, "roam*"]
    Others: [mark, fuse]

That is, the keys are group titles, and each value is either the contents or a map with desc and contents.

If no groups are provided, pkg_manual() lists topics alphabetically, and pkg_articles() and pkg_examples() list all items in a single list.

overview

Whether to include the package overview page, i.e., the {name}-package.Rd page.

examples

A list of arguments to be passed to xfun::record() to run examples each help page, e.g., list(dev = 'svg', dev.args = list(height = 6)). If not a list (e.g., FALSE), examples will not be run.

Examples

if (FALSE) {
litedown::pkg_desc()
litedown::pkg_news()
litedown::pkg_citation()
}