Title: Markdown Reference Manuals
Version: 1.0.1
Description: Native R only allows PDF exports of reference manuals. The 'Rd2md' package converts the package documentation files into markdown files and combines them into a markdown version of the package reference manual.
Depends: R (≥ 3.6)
Imports: tools
Suggests: knitr, testthat, rmarkdown, devtools
License: GPL-2 | GPL-3 [expanded from: GPL]
Encoding: UTF-8
VignetteBuilder: knitr
RoxygenNote: 7.2.3
URL: https://github.com/quantsch/rd2md
BugReports: https://github.com/quantsch/rd2md/issues
NeedsCompilation: no
Packaged: 2024-06-17 19:48:07 UTC; runner
Author: Julian Busch [aut, cre]
Maintainer: Julian Busch <jb@quants.ch>
Repository: CRAN
Date/Publication: 2024-06-17 20:00:02 UTC

Reference Manual in Markdown

Description

Functions to parse and convert Rd files to markdown format reference manual.

Author(s)

Julian Busch jb@quants.ch

See Also

knitr

Rd file to markdown

Description

This function converts an Rd file into markdown format.

Arguments

rdfile

Filepath to an .Rd file or an Rd object to parse.

outfile

Filepath to output file (markdown file).

append

If outfile exists, append to existing content.

Value

Parsed Rd as named list

See Also

Rd2md-deprecated

Examples

## give a markdown source file
rdfile = "~/git/MyPackage/man/myfun.Rd"
## specify, where markdown shall be stored
outfile = "/var/www/html/R_Web_app/md/myfun.md"
## create markdown
## Rd2markdown(rdfile = rdfile, outfile = outfile)

Deprecated functions in package Rd2md.

Description

The functions listed below are deprecated and will be defunct in the near future. When possible, alternative functions with similar functionality are also mentioned. Help pages for deprecated functions are available at help("<function>-deprecated").

Usage

ReferenceManual(
  pkg = getwd(),
  outdir = getwd(),
  front.matter = "",
  toc.matter = "<!-- toc -->",
  date.format = "%B %d, %Y",
  verbose = FALSE
)

Rd2markdown(rdfile, outfile, append = FALSE)

ReferenceManual

For ReferenceManual(), use render_refman().

Rd2markdown

For Rd2markdown(), use as_markdown().

Create Reference Manual Markdown

Description

This is a wrapper to combine the Rd files of a package source or binary into a reference manual in markdown format.

Arguments

pkg

Full path to package directory. Default value is the working directory. Alternatively, a package name can be passed. If this is the case, find.package is applied.

outdir

Output directory where the reference manual markdown shall be written to.

front.matter

String with yaml-style heading of markdown file.

toc.matter

String providing the table of contents. This is not auto-generated. The default value is a HTML comment, used by gitbook plugin toc.

date.format

Date format that shall be written to the beginning of the reference manual. If NULL, no date is written. Otherwise, provide a valid format (e.g. %Y-%m-%d), see Details in strptime.

verbose

If TRUE all messages and process steps will be printed

References

Murdoch, D. (2010). Parsing Rd files

See Also

Rd2md-deprecated and package Rd2markdown by jbryer

Examples

## give source directory of your package
pkg_dir = "~/git/MyPackage"

## specify, where reference manual shall be stored
out_dir = "/var/www/html/R_Web_app/md/"

## create reference manual
## ReferenceManual(pkg = pkg_dir, outdir = out_dir)

Parse into Markdown

Description

S3 Methods to parse different classes into Markdown.

Usage

as_markdown(x, ...)

Arguments

x

Object

...

Further arguments passed to methods

Output Format Markdown

Description

Specifies markdown output format parameters.

Usage

md_document(
  file_ext = ".md",
  section_level = 1,
  date_format = "%F",
  toc = FALSE
)

Arguments

file_ext

File extension, if default output_file name

section_level

Initial section level, subsection level n will consequently be section_level + n

date_format

See format argument of base::strptime()

toc

Currently not implemented. If table of contents should be included in reference manual.

Output Format Definition

Description

Specifies output format parameters.

Usage

output_format(output_class_suffix, file_ext, parse_fun, ...)

Arguments

output_class_suffix

Suffix to class name. E.g. md for output_format_md.

file_ext

File extension, if default output_file name.

parse_fun

Parsing function, should be a generic S3 method.

...

Named arguments inserted into list structure output and eventually passed as arguments to parse_fun.

Translate an Rd string to markdown

Description

Note that this will always end in one newline \n.

Usage

rd_str_to_md(x, fragment = TRUE, ...)

Arguments

x

Rd string. Backslashes must be double-escaped ("\\").

fragment

logical indicating whether this represents a complete Rd file

...

additional arguments for as_markdown

Examples

rd_str_to_md("a\n%b\nc")

rd_str_to_md("a & b")

rd_str_to_md("\\strong{\\emph{x}}")

rd_str_to_md("\\enumerate{\\item test 1\n\n\\item test 2}")
rd_str_to_md("wrapped \\itemize{\\item test 1\n\\item test 2} in text")

Read .Rd file

Description

And return object of class rdfile

Usage

read_rdfile(path, subclass = NULL)

Arguments

path

File path of ⁠*.Rd⁠-file

subclass

Potential subclass of returned rdfile object

Create Markdown Reference Manual

Description

This is a wrapper to combine the Rd files of a package source or binary into a reference manual in markdown format.

Usage

render_refman(pkg = getwd(), output_file = NULL, output_format = md_document())

Arguments

pkg

Full path to package directory. Default value is the current working directory. Alternatively, a package name can be passed as string. If this is the case, base::find.package() is applied.

output_file

Specify outputfile, including file extension

output_format

Output format function. See output_format(). Default is md_document(), but one could provide a custom output format.

References

Murdoch, D. (2010). Parsing Rd files

See Also

Examples

## give source directory of your package
pkg_dir = "~/git/MyPackage"

## create reference manual
## render_refman(pkg_dir)