Render a Rd object out to a markdown file

LIST Rd tags are produced with an unnamed infotex function call. Whereas normal infotex syntax follows a \name{arg} convention, naked {arg} will be captured as a LIST. This syntax has been adopted as a convention for package names. The desired rendering of this element is often ambiguous. To try to accommodate as many cases as possible, it is rendered as plain text.

Usage

rd2markdown(x, fragments = c(), ...)

# S3 method for class 'Rd'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'list'
rd2markdown(x, fragments = c(), ...)

# S3 method for class '`NULL`'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'AsIs'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'name'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'alias'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'keyword'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'concept'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'USERMACRO'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'code'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'RCODE'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'verb'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'pkg'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'env'
rd2markdown(x, fragments = c(), ...)

# Default S3 method
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'title'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'description'
rd2markdown(x, fragments = c(), ..., title = "Description", level = 2L)

# S3 method for class 'author'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'format'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'details'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'note'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'source'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'value'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'section'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'subsection'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'examples'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'usage'
rd2markdown(..., level = 2L)

# S3 method for class 'preformatted'
rd2markdown(x, fragments = c(), ..., title = NULL, language = "", level = 2L)

# S3 method for class 'references'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'seealso'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'arguments'
rd2markdown(x, fragments = c(), ..., level = 2L)

# S3 method for class 'dots'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'TEXT'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'COMMENT'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'character'
rd2markdown(
  x = NULL,
  fragments = c(),
  ...,
  topic = NULL,
  package = NULL,
  file = NULL,
  macros = NULL,
  envir = parent.frame()
)

# S3 method for class 'emph'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'item'
rd2markdown(x, fragments = c(), ..., item_style = "**")

# S3 method for class 'enumerate'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'itemize'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'describe'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'LIST'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'tabular'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'tab'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'cr'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'href'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'url'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'eqn'
rd2markdown(x, fragments = c(), ...)

# S3 method for class 'deqn'
rd2markdown(x, fragments = c(), ...)

Arguments

x

An Rd object, list, help topic or Rd tag to convert into markdown-formatted help.

fragments

An optional vector of fragment tag names (such as "description", "details" or "title") to filter the Rd object tags.

...

Additional arguments used by specific methods.

title

optional section title

level

optional level parameter. 2L by default

language

language to use as code fence syntax highlighter

topic

usually, a name or character string specifying the topic for which help is sought. A character string (enclosed in explicit single or double quotes) is always taken as naming a topic.

If the value of topic is a length-one character vector the topic is taken to be the value of the only element. Otherwise topic must be a name or a reserved word (if syntactically valid) or character string.

See ‘Details’ for what happens if this is omitted.

package

a name or character vector giving the packages to look into for documentation, or NULL. By default, all packages whose namespaces are loaded are used. To avoid a name being deparsed use e.g. (pkg_ref) (see the examples).

file

Alternatively, provide a .Rd filepath. When file is provided, other arguments are ignored.

macros

Filename or environment from which to load additional macros, or a logical value. See the Details below.

envir

An optional environment in which to search for the help topic

item_style

Used for two-part \\item tags, item_style defines the fencing characters to use for the item name. Defaults to "**", which will format item names using bold-face markdown syntax.

Details

rd2markdown is the core function of the package. can work in various types. It accepts .Rd objects extracted with get_rd option but also can directly fetch documentation topics based on the file path or the package. Due to the design, it follows, rd2markdown function has high flexibility. It is worth pointing out that the actual output of rd2markdown function is a character vector of length one that uses special signs to format the document. Use writeLines function to create an actual markdown file using this output. The rd2markdown function parses documentation object based on an innovative idea of treating each .Rd tag as a separate class and implementing methods for those classes. Thanks to that the package is easily extensible and clear to understand. To see the list of currently supported tags please see the Usage section.

Examples


# Using get_rd
rd_file_example <- system.file("examples", "rd_file_sample.Rd", package = "rd2markdown")
rd <- rd2markdown::get_rd(file = rd_file_example)
cat(rd2markdown::rd2markdown(rd))
#> # Rd sampler title
#> 
#> ```r
#> rd_sampler(x, y = TRUE, ...)
#> ```
#> 
#> ## Arguments
#> 
#> - `x`: Rd sampler param
#> - `y`: Rd sampler param with default
#> - `...`: Rd sampler ellipsis param
#> 
#> ## Returns
#> 
#> Rd sampler return
#> 
#> ## Description
#> 
#> Rd sampler description with [Rd sampler link](www.example.com), `Rd sampler in-line code`. And Rd dynamic content, **italics text**, **emphasis text**.
#> 
#> ## Details
#> 
#> Rd sampler details
#> 
#> Rd sampler enumerated list
#> 
#> 1. One
#> 2. Two
#> 3. Three
#> 
#> Rd sampler itemized list
#> 
#>  * One
#>  * Two
#>  * Three
#> 
#> ||||
#> |:--|:--|:--|
#> |Rd|Sampler|Table|
#> |rd|sampler|table|
#> 
#> `Rd + sampler + inline + equation`
#> 
#> `Rd * sampler * block * equation`
#> 
#> ## Note
#> 
#> Rd sampler note
#> 
#> ## Rd sampler subsection
#> 
#> Rd sampler subsection text
#> 
#> ### Rd sampler sub-subsection
#> 
#>  Rd sampler sub-subsection text
#> 
#> ## Examples
#> 
#> ```r
#> rd_sampler()
#> ```
#> 
#> ## References
#> 
#> R.D. Sampler. (2021)
#> 
#> ## See Also
#> 
#> base::print
#> 
#> ## Author(s)
#> 
#> R.D. Sampler.
#> 
#> 

# Limit to particular sections
rd <- rd2markdown::get_rd(file = rd_file_example)
cat(rd2markdown::rd2markdown(rd, fragments = c("description", "usage")))
#> ```r
#> rd_sampler(x, y = TRUE, ...)
#> ```
#> 
#> ## Description
#> 
#> Rd sampler description with [Rd sampler link](www.example.com), `Rd sampler in-line code`. And Rd dynamic content, **italics text**, **emphasis text**.

# Use file parameter
cat(rd2markdown::rd2markdown(file = rd_file_example))
#> # Rd sampler title
#> 
#> ```r
#> rd_sampler(x, y = TRUE, ...)
#> ```
#> 
#> ## Arguments
#> 
#> - `x`: Rd sampler param
#> - `y`: Rd sampler param with default
#> - `...`: Rd sampler ellipsis param
#> 
#> ## Returns
#> 
#> Rd sampler return
#> 
#> ## Description
#> 
#> Rd sampler description with [Rd sampler link](www.example.com), `Rd sampler in-line code`. And Rd dynamic content, **italics text**, **emphasis text**.
#> 
#> ## Details
#> 
#> Rd sampler details
#> 
#> Rd sampler enumerated list
#> 
#> 1. One
#> 2. Two
#> 3. Three
#> 
#> Rd sampler itemized list
#> 
#>  * One
#>  * Two
#>  * Three
#> 
#> ||||
#> |:--|:--|:--|
#> |Rd|Sampler|Table|
#> |rd|sampler|table|
#> 
#> `Rd + sampler + inline + equation`
#> 
#> `Rd * sampler * block * equation`
#> 
#> ## Note
#> 
#> Rd sampler note
#> 
#> ## Rd sampler subsection
#> 
#> Rd sampler subsection text
#> 
#> ### Rd sampler sub-subsection
#> 
#>  Rd sampler sub-subsection text
#> 
#> ## Examples
#> 
#> ```r
#> rd_sampler()
#> ```
#> 
#> ## References
#> 
#> R.D. Sampler. (2021)
#> 
#> ## See Also
#> 
#> base::print
#> 
#> ## Author(s)
#> 
#> R.D. Sampler.
#> 
#> 

# Use topic and package parameters
cat(
  rd2markdown::rd2markdown(
    topic = "rnorm",
    package = "stats",
    fragments = c("description", "usage")
  )
)
#> ## Description
#> 
#> Density, distribution function, quantile function and random generation for the normal distribution with mean equal to `mean` and standard deviation equal to `sd`.
#> 
#> ```r
#> dnorm(x, mean = 0, sd = 1, log = FALSE)
#> pnorm(q, mean = 0, sd = 1, lower.tail = TRUE, log.p = FALSE)
#> qnorm(p, mean = 0, sd = 1, lower.tail = TRUE, log.p = FALSE)
#> rnorm(n, mean = 0, sd = 1)
#> ```

Render a Rd object out to a markdown file

Usage

Arguments

Details

See also

Examples