Package 'rdoc'

Colourised R documentation

Description

Refer to colourised R docs as terminal output. Provides a replacement for help. A number of common (substantive) section accessors are also provided.

Usage

rdoc(topic, package = NULL, lib.loc = NULL)

rdoc_usage(topic, package = NULL, lib.loc = NULL)

rdoc_arguments(topic, package = NULL, lib.loc = NULL)

rdoc_details(topic, package = NULL, lib.loc = NULL)

rdoc_examples(topic, package = NULL, lib.loc = NULL)

Arguments

topic	character(1), help topic
package	character(1), package of help topic. Defaults to NULL
lib.loc	character(1), library location of package. Defaults to NULL

Details

The manner in which content is outputted depends on where it is being used. If used from a terminal the contents will be outputted via file.show. Otherwise the output will be printed interactively by sections unless this has been disabled via options(rdoc.by_section = FALSE). When printing by section pressing the <enter> keypress will show the next section. Any other keypress will exit the interaction without printing any remaining sections. Color support is checked via crayon::has_color(). Customising rdoc output is possible via 'options', see rdoc_options for more details.

Examples

library(rdoc)
rdoc("rdoc")
rdoc_examples("min")
rdoc_usage(substr)

---

rdoc options

Description

Rdoc uses the following options() to set output:

• 'rdoc.by_section': logical, output interactively printed by sections for console sessions. Sections will be printed with the <enter> keypress. Any other keypress will exit the interaction without printing the remaining sections. Default is TRUE.

• 'rdoc.header': logical, whether package header is included in the output. Default is TRUE.

• 'rdoc.text_formats': see rdoc_text_formats

• 'rdoc.style': see rdoc_style

• 'rdoc.item_bullet': Symbol to use for itemized lists. Default is paste0(cli::symbol$circle, " ")

---

Colourised R documentation

Description

Refer to colourised R docs as terminal output. Provides a replacement for ?. Meant primarily for use as an override in use_rdoc()

Usage

rdoc_question(type, topic)

Arguments

type	the special type of documentation to use for this topic; for example, if the type is class, documentation is provided for the class with name topic. See the Section ‘S4 Method Documentation’ for the uses of type to get help on formal methods, including methods?function and method?call.
topic	Usually, a name or character string specifying the topic for which help is sought. Alternatively, a function call to ask for documentation on a corresponding S4 method: see the section on S4 method documentation. The calls pkg::topic and pkg:::topic are treated specially, and look for help on topic in package pkg.

Details

The manner in which content is outputted depends on where it is being used. If used from a terminal the contents will be outputted via file.show. Otherwise the output will be printed interactively by sections unless this has been disabled via options(rdoc.by_section = FALSE). When printing by section pressing the <enter> keypress will show the next section. Any other keypress will exit the interaction without printing any remaining sections. Color support is checked via crayon::has_color(). Customising rdoc output is possible via 'options', see rdoc_options for more details.

Examples

rdoc::rdoc_question('lapply')

---

Colourised R documentation

Description

Refer directly to .Rd file contents as terminal output.

Usage

rdoc_rd(path)

Arguments

path	character(1), the path to an .Rd file

Details

The manner in which content is outputted depends on where it is being used. If used from a terminal the contents will be outputted via file.show. Otherwise the output will be printed interactively by sections unless this has been disabled via options(rdoc.by_section = FALSE). When printing by section pressing the <enter> keypress will show the next section. Any other keypress will exit the interaction without printing any remaining sections. Color support is checked via crayon::has_color(). Customising rdoc output is possible via 'options', see rdoc_options for more details.

Examples

d <- system.file('extdata/rdoc_test.Rd', package = "rdoc")
rdoc::rdoc_rd(d)

---

rdoc style options

Description

Set Rd output formatting styles to be supplied to options(rdoc.style = rdoc_style())

Usage

rdoc_style(title = crayon::bold, section_titles = crayon::underline,
  arguments = NULL, code_style = prettycode::default_style())

Arguments

title	topic title.
section_titles	section titles
arguments	argument parameters.
code_style	code sections (e.g. examples) and inline code styles to be passed on to prettycode::highlight

Details

all inputs should be functions or NULL with the exception of code_style which should be a list of functions.

Value

A list

Examples

options(rdoc.style = rdoc::rdoc_style(arguments = crayon::italic))

---

Colourised R documentation

Description

Access the underlying rdoc text lines

Usage

rdoc_text(topic, package = NULL, lib.loc = NULL)

Arguments

topic	character(1), help topic
package	character(1), package of help topic. Defaults to NULL
lib.loc	character(1), library location of package. Defaults to NULL

Value

character

Examples

txt <- rdoc::rdoc_text('min')

---

Rdoc text formatting

Description

Set Rd text format defaults to be supplied to options(rdoc.text_formats = rdoc_text_formats())

Usage

rdoc_text_formats(r_logo = crayon::combine_styles("bold", "blue"),
  pkg = function(x) paste0("{", x, "}"),
  inline_code = prettycode::default_style(), italic = crayon::italic,
  bold = crayon::bold, table = list(float = "center", border_style =
  "single", align = "left"), email = crayon::underline,
  url = crayon::underline, href = crayon::underline,
  link = function(x) x)

Arguments

r_logo	R symbol
pkg	pkg references
inline_code	inline code, options to pass to the style argument of prettycode::highlight as a list of functions.
italic	italic font
bold	bold font
table	tabular, options to pass to cli::boxx as a list.
email	email formats
url	url references
href	href
link	links

Details

The input will generally be a function, unless otherwise indicated above. Functions must take and return a character vector. If set as NULL, the relevant text will be displayed using the defaults of tools::Rd2txt or the calling function it is passed to. Note that href and link formatting refer to the source reference which will otherwise be excluded by tools::Rd2txt.

---

Base replacements

Description

rdoc replacements for ? and help

Usage

use_rdoc()

rm_rdoc()

Details

Calling use_rdoc() will override utils::`?` with rdoc_question and utils::help with rdoc. As a convenience, use_rdoc() loads utils first. This ensures that if use_rdoc() is set in an .Rprofile the replacements will stay ahead of utils in the search path after startup is finished. These replacements can be unset by calling rm_rdoc() (note that no detachment will occur for utils here).

Examples

rdoc::use_rdoc()
?help
rdoc::rm_rdoc()
?help

---