pd$Description
pd$Author
Maintainer: pd$Maintainer
Package Rdpack provides a number of functions for maintenance
of documentation in R packages. Although base R and
package methods have functions for creation of skeleton
documentation, if a function gets a new argument or a generic gets a
new method, then updating existing documentation is somewhat
inconvenient. This package provides functions that update parts of the
Rd documentation that can be dealt with automatically and leave manual
changes untouched. For example, usage sections for functions are
updated and if there are undescribed arguments, additional items are
put in the `arguments' section.
A set of functions and macros support inclusion of references and citations from BibTeX files in R documentation (Rd and roxygen2). These tools use only facilities provided by base R and package rbibutils if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(keys="Rpackage:rbibutils",package="Rdpack", cached_env=.Rdpack.currefs).
There are also convenience macros for inclusion of evaluated examples
and graphs, which hide some of the hassle of doing this directly with
the underlying \Sexpr's.
The subsections below give additional details, see also the vignettes.
The main function provided by this package is reprompt.
There is also a function promptPackageSexpr for creating
initial skeleton for overall package description such as this help
page.
reprompt produces a skeleton documentation for the
requested object, similarly to functions like prompt,
promptMethods, and promptClass. Unlike those functions,
reprompt updates existing documentation (installed or in
an Rd object or file) and produces a skeleton from scratch as a last
resort only. If the documentation object describes more than one
function, all descriptions are updated. Basically,
reprompt updates things that are generated
automatically, leaving manual editing untouched.
The typical use of reprompt is with one argument, as in
reprompt(infile = "./Rdpack/man/reprompt.Rd")
reprompt(reprompt)
reprompt("reprompt")
reprompt updates the documentation of all objects described in
the Rd object or file, and writes the updated Rd file in the current
working directory, see reprompt for details. To describe
a new function in an existing Rd file, just add something like
myfun() and run reprompt to insert the correct signature,
alias, etc. This works also for replacement functions, see
reprompt for details.
ereprompt updates the Rd documentation in a file,
overwrites it and opens it in an editor. It calls reprompt to
do the actual job but has different defaults. Which editor is opened,
is system dependent, see the edit and
ereprompt for futher details.
Users who work on Rd files in RStudio can use add-in “Reprompt”
to invoke reprompt conveniently on an Rd file or on a selected
object in an R source code file, see
RStudio_reprompt. This add-in was contributed by Duncan
Murdoch.
Users of Emacs/ESS have various options, depending on their workflow.
One approach is to define a key to call ereprompt on the
file being edited, see
georgisemacs for an
example setup.
promptPackageSexpr creates a skeleton for a
package overview in file name-package.Rd. Then the file can be
edited as needed. This function needs to be called only once for a
package since automatic generation of information in
name-package.Rd is achieved with Sexpr's at build time, not
with verbatim strings (promptPackage used to insert verbatim
strings but in recent versions of R it also uses macros.).
For example, the source of this help page is file `Rdpack-package.Rd'. It was initially produced using
promptPackageSexpr("Rdpack")
The factual information at the beginning of this help topic (the index above, the version and other stuff that can be determined automatically) is kept automatically up to date.
Another set of functions is for management of bibliographic references
in Rd files. The old approach based on function rebib
is fully functional, see below, but the recommended way to insert
references and citations is based on Rd macros.
The provided Rd macros are fully portable and, in particular, work in
Rd files and roxygen2 comments, see insertRef and
vignette vignette("Inserting_bibtex_references", "Rdpack")
for details and examples.
The Bibtex source for the references and citations produced by the Rd macros is file "REFERENCES.bib", which should be located in the root of the package installation directory. Rdpack needs also to be mentioned in two places in file `DESCRIPTION'. These one-off preparation steps are enumerated below:
Put the following line in file `DESCRIPTION':
RdMacros: Rdpack
(If there is already a line starting with 'RdMacros:', add
Rdpack to the list on that line.)
Add Rdpack to the list of imports (Imports:
field) in file `DESCRIPTION'.
Add the following line to file `NAMESPACE':
importFrom(Rdpack,reprompt)
#' @importFrom Rdpack repromptCreate file "REFERENCES.bib" in subdirectory
"inst/" of the package and put the BibTeX references in
that file.
The Rd macro \insertRef takes two arguments: a BibTeX key and
the name of a package. Thus, \insertRef{key}{package} inserts
the reference whose key is key from "REFERENCES.bib" of the
specified package (almost always the one being documented).
Citations can be done with Rd
macro \insertCite, which inserts citation(s) for one or more
BibTeX keys and records the keys. \insertCiteOnly is similar
to \insertCite but does not record the
keys. \insertNoCite records the keys but does not produce
citations.
\insertAllCited creates a bibliography including
all references recorded by \insertCite and
\insertNoCite. It is usually put in section
“References”, something like:
\references{
\insertAllCited{}
}
in an Rd file. The analogous documentation chunk in roxygen2 might look like this:
#' @references
#' \insertAllCited{}
Don't align the backslash with the second 'e' of @references,
since roxygen2 may interpret it as verbatim text, not macro.
Bibliography styles for lists of references are supported as well. Currently the only alternative offered is to use long names (Georgi N. Boshnakov) in place of the default style (Boshnakov GN). More comprehensive alternatives can be included if needed or requested.
Convenience functions makeVignetteReference and
vigbib generate Bibtex entries for vignettes.
It is convenient during development to be able to view the
rendered version of the document page being edited.
The function viewRd renders a documentation file in a
source package and displays it as text or in a browser. It renders
references properly in any workflow, including devtools development
mode if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(keys="Rdevtools",package="Rdpack", cached_env=.Rdpack.currefs) in Emacs/ESS, Rstudio, Rgui.
This function is a good candidate to be assigned to a key in editors
which support this.
I created this function (in 2017) since the functions provided by devtools and Emacs/ESS are giving errors when processing pages containing Rd macros.
In the alternative approach, the function rebib updates
the bibliographic references in an Rd file. Rdpack uses a simple
scheme for inclusion of bibliographic references. The key for each
reference is in a TeX comment line, as in:
\references{
...
% bibentry: key1
% bibentry: key2
...
}
rebib puts each reference after the line containing its
key. It does nothing if the reference has been put by a previous call
of rebib. If the Bibtex entry for some references changes, it
may be necessary to update them in the Rd file, as well. Call
rebib with force = TRUE to get this effect. There is
also a facility to include all references from the Bibtex file, see
the documentation of rebib for details.
Sometimes the documentation of an object becomes more clear if accompanied by snippets of R
code and their results.
The standard Rd macro \Sexpr caters for a number of possibilities to evaluate R code and
insert the results and the code in the documentation.
The Rd macro \printExample provided by package
Rdpack builds on it to print a snippet of R code and the results of its evaluation, similarly to
console output but the code is not prefixed and the results are prefixed with comment
symbols.
For example, \printExample{2+2; a <- 2*3; a} produces the
following in the rendered documentation:
.Rdpack.e <- environment();Rdpack:::run_examples(quote({2+2; a <- 2*3; a}), local = .Rdpack.e, Rdsection = "preformatted")
The help page of promptUsage contains a number of examples created with
\printExample. The corresponding Rd file can be obtained from the package tarball or from
https://github.com/GeoBosh/Rdpack/blob/master/man/promptUsage.Rd.
The argument of \printExample must be on a single line with versions of R before
R 3.6.0.
\printExample is typically placed in section Details of an
object's documentation, see section Details of get_usage
for a number of examples produced mostly with \printExample.
The macro \runExamples can be used as a replacement
of section Examples.
For example, if the following code is put at the top level in an Rd file (i.e. not in a
section):
\runExamples{2+2; a <- 2*3; a}
then it will be evaluated and replaced by a normal section examples:
\examples{
2 + 2
##: 4
a <- 2 * 3
a
##: 6
}
This generated examples section is processed by the standard R tools (almost) as if it was there from the outset. In particular, the examples are run by the R's quality control tools and tangled along with examples in other documentation files.
In R versions before 3.6.0 R CMD check used to give a warning about
unknown \Sexpr section at top level.
Figures can be inserted with the help of the standard Rd markup command
\figure. The Rd macro \insertFig provided by package
Rdpack takes a snipped of R code, evaluates it and inserts the
plot produced by it (using \figure). \insertFig takes
three arguments: a filename, the package name and the code to evaluate
to produce the figure. For example,
\insertFig{cars.png}{mypackage}{x <- cars$speed; y <- cars$dist; plot(x,y)}
will evaluate the code, save the graph in file "man/figures/cars.png" subdirectory of
package "mypackage", and include the figure using \figure.
Subdirectory "figures" is created if it doesn't exist.
Currently the graphs are saved in "png" format only.
In older versions of R the code should be on a single line for the reasons explained in the
discussion of \printExample.
The sister macro \makeFig creates the graph in exactly the same
way as \insertFig but does not insert it. This can be done with a
separate \figure command. This can be used if additional options are
desired for different output formats, see the description of \figure
in "Writing R extensions".
Other functions that may be useful are Rdo2Rdf, Rdapply
and Rd_combo. Here is also brief information about some more
technical functions that may be helpful in certain circumstances.
get_usage generates usage text for functions and
methods. The functions can be located in environments or other
objects. This may be useful for description of function elements of
compound objects.
c_Rd concatenates Rd pieces, character strings and lists
to create a larger Rd piece or a complete Rd object.
list_Rd is similar to c_Rd but provides
additional features for convenient assembling of Rd objects.
parse_Rdpiece is a technical function for parsing pieces
of Rd source text but it has an argument to return formatted help text
which may be useful when one wishes to show it to the user.
Rdo_set_section can be used to set a section, such as
"\author".
The remaining functions in the package are for programming with Rd objects.
Note 1: Reference if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(keys="dummyArticle;textual",package="Rdpack", cached_env=.Rdpack.currefs) (see below) does not exist. It is a test that simple math in BibTeX entries works.
Note 2: Reference if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_citeOnly(keys="unpublished-full;textual",package="rbibutils", cached_env=.Rdpack.currefs) is included to show that some more and less usual accents are handled.
---
if(!exists(".Rdpack.currefs")) .Rdpack.currefs <- new.env();Rdpack::insert_all_ref(.Rdpack.currefs)
ereprompt,
reprompt,
promptPackageSexpr,
rebib,
get_usage,
viewRd,
vigbib,
makeVignetteReference,
vignette("Inserting_bibtex_references", package = "Rdpack"),
vignette("Inserting_figures_and_evaluated_examples", package = "Rdpack")
## The examples below show typical use but are not executable.
## For executable examples see the help pages of
## reprompt, promptPackageSexpr, and rebib.
## To make the examples executable, replace "myfun" with a real
## function, and similarly for classes and paths to files.
if (FALSE) {
## update the doc. from the Rd source and save myfun.Rd
## in the current directory (like prompt)
reprompt(infile="path/to/mypackage/man/myfun.Rd")
## update doc of myfun() from the installed doc (if any);
## if none is found, create it like prompt
reprompt("myfun")
reprompt(myfun) # same
## update doc. for S4 methods from Rd source
reprompt(infile="path/to/mypackage/man/myfun-methods.Rd")
## update doc. for S4 methods from installed doc (if any);
## if none is found, create it like promptMethods
reprompt("myfun", type = "methods")
reprompt("myfun-methods") # same
## update doc. for S4 class from Rd source
reprompt(infile="path/to/mypackage/man/myclass-class.Rd")
## update doc. of S4 class from installed doc.
## if none is found, create it like promptClass
reprompt("myclass-class")
reprompt("myclass", type = "class") # same
## create a skeleton "mypackage-package.Rd"
promptPackageSexpr("mypackage")
## update the references in "mypackage-package.Rd"
rebib(infile="path/to/mypackage/man/mypackage-package.Rd", force=TRUE)
}
Run the code above in your browser using DataLab