knitr: spin – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

spin

Spin goat's hair into wool

Description

This function takes a specially formatted R script and converts it to a literate programming document. By default normal text (documentation) should be written after the roxygen comment (#') and code chunk options are written after #+ or #- or # ---- or any of these combinations replacing # with --.

Usage

spin(
  hair,
  knit = TRUE,
  report = TRUE,
  text = NULL,
  envir = parent.frame(),
  format = c("Rmd", "Rnw", "Rhtml", "Rtex", "Rrst"),
  doc = "^#+'[ ]?",
  inline = "^[{][{](.+)[}][}][ ]*$",
  comment = c("^[# ]*/[*]", "^.*[*]/ *$"),
  precious = !knit && is.null(text)
)

Arguments

`hair`	Path to the R script. The script must be encoded in UTF-8 if it contains multibyte characters.
`knit`	Logical; whether to compile the document after conversion.
`report`	Logical; whether to generate a report for ‘Rmd’, ‘Rnw’ and ‘Rtex’ output. Ignored if `knit = FALSE`.
`text`	A character vector of code, as an alternative way to provide the R source. If `text` is not `NULL`, `hair` will be ignored.
`envir`	Environment for `knit()` to evaluate the code.
`format`	Character; the output format. The default is R Markdown.
`doc`	A regular expression to identify the documentation lines; by default it follows the roxygen convention, but it can be customized, e.g. if you want to use `##` to denote documentation, you can use `'^##\\s*'`.
`inline`	A regular expression to identify inline R expressions; by default, code of the form `{{code}}` on its own line is treated as an inline expression.
`comment`	A pair of regular expressions for the start and end delimiters of comments; the lines between a start and an end delimiter will be ignored. By default, the delimiters are `/` at the beginning of a line, and `/` at the end, following the convention of C comments.
`precious`	logical: whether intermediate files (e.g., `.Rmd` files when `format` is `"Rmd"`) should be preserved. The default is `FALSE` if `knit` is `TRUE` and the input is a file.

Details

Obviously the goat's hair is the original R script, and the wool is the literate programming document (ready to be knitted).

Value

If text is NULL, the path of the final output document, otherwise the content of the output.

Note

If the output format is Rnw and no document class is specified in roxygen comments, this function will automatically add the article class to the LaTeX document so that it is complete and can be compiled. You can always specify the document class and other LaTeX settings in roxygen comments manually.

When the output format is Rmd, it is compiled to HTML via knit2html(), which uses R Markdown v1 instead of v2. If you want to use the latter, you should call rmarkdown::render() instead.

Author(s)

Yihui Xie, with the original idea from Richard FitzJohn (who named it as sowsear() which meant to make a silk purse out of a sow's ear)

References

https://yihui.org/knitr/demo/stitch/

Yihui Xie [aut, cre] (<https://orcid.org/0000-0003-0645-5666>), Abhraneel Sarma [ctb], Adam Vogt [ctb], Alastair Andrew [ctb], Alex Zvoleff [ctb], Andre Simon [ctb] (the CSS files under inst/themes/ were derived from the Highlight package http://www.andre-simon.de), Aron Atkins [ctb], Aaron Wolen [ctb], Ashley Manton [ctb], Atsushi Yasumoto [ctb] (<https://orcid.org/0000-0002-8335-495X>), Ben Baumer [ctb], Brian Diggs [ctb], Brian Zhang [ctb], Bulat Yapparov [ctb], Cassio Pereira [ctb], Christophe Dervieux [ctb], David Hall [ctb], David Hugh-Jones [ctb], David Robinson [ctb], Doug Hemken [ctb], Duncan Murdoch [ctb], Elio Campitelli [ctb], Ellis Hughes [ctb], Emily Riederer [ctb], Fabian Hirschmann [ctb], Fitch Simeon [ctb], Forest Fang [ctb], Frank E Harrell Jr [ctb] (the Sweavel package at inst/misc/Sweavel.sty), Garrick Aden-Buie [ctb], Gregoire Detrez [ctb], Hadley Wickham [ctb], Hao Zhu [ctb], Heewon Jeon [ctb], Henrik Bengtsson [ctb], Hiroaki Yutani [ctb], Ian Lyttle [ctb], Hodges Daniel [ctb], Jake Burkhead [ctb], James Manton [ctb], Jared Lander [ctb], Jason Punyon [ctb], Javier Luraschi [ctb], Jeff Arnold [ctb], Jenny Bryan [ctb], Jeremy Ashkenas [ctb, cph] (the CSS file at inst/misc/docco-classic.css), Jeremy Stephens [ctb], Jim Hester [ctb], Joe Cheng [ctb], Johannes Ranke [ctb], John Honaker [ctb], John Muschelli [ctb], Jonathan Keane [ctb], JJ Allaire [ctb], Johan Toloe [ctb], Jonathan Sidi [ctb], Joseph Larmarange [ctb], Julien Barnier [ctb], Kaiyin Zhong [ctb], Kamil Slowikowski [ctb], Karl Forner [ctb], Kevin K. Smith [ctb], Kirill Mueller [ctb], Kohske Takahashi [ctb], Lorenz Walthert [ctb], Lucas Gallindo [ctb], Marius Hofert [ctb], Martin Modrák [ctb], Michael Chirico [ctb], Michael Friendly [ctb], Michal Bojanowski [ctb], Michel Kuhlmann [ctb], Miller Patrick [ctb], Nacho Caballero [ctb], Nick Salkowski [ctb], Niels Richard Hansen [ctb], Noam Ross [ctb], Obada Mahdi [ctb], Pavel N. Krivitsky [ctb] (<https://orcid.org/0000-0002-9101-3362>), Qiang Li [ctb], Ramnath Vaidyanathan [ctb], Richard Cotton [ctb], Robert Krzyzanowski [ctb], Romain Francois [ctb], Ruaridh Williamson [ctb], Scott Kostyshak [ctb], Sebastian Meyer [ctb], Sietse Brouwer [ctb], Simon de Bernard [ctb], Sylvain Rousseau [ctb], Taiyun Wei [ctb], Thibaut Assus [ctb], Thibaut Lamadon [ctb], Thomas Leeper [ctb], Tim Mastny [ctb], Tom Torsney-Weir [ctb], Trevor Davis [ctb], Viktoras Veitas [ctb], Weicheng Zhu [ctb], Wush Wu [ctb], Zachary Foster [ctb]

Initial release