Run 'roxygen2' on (Chunks of) Single Code Files

Have you ever been tempted to create 'roxygen2'-style documentation comments for one of your functions that was not part of one of your packages (yet)? This is exactly what this package is about: running 'roxygen2' on (chunks of) a single code file.

Build Status Coverage Status CRAN_Status_Badge RStudio_downloads_monthly RStudio_downloads_total


Please read the vignette.

Or, after installation, the help page:

help("document-package", package = "document")
# Document a Single R Code File
# Description:
#      Have you ever been tempted to create 'roxygen2'-style
#      documentation comments for one of your functions that was not part
#      of one of your packages (yet)? This is exactly what this package
#      is about: running 'roxygen2::roxygenize' on (chunks of) a single
#      code file.
#      This package enables you to
#        1. create function documentation with 'roxygen2'
#        2. detect code/documentation mismatches
#        3. save the documentation to disk
#        4. view the documentation in your interactive R session
#      You will probably be looking for 'document' and 'man', the
#      remaining functions documented here are mainly for internal use.
# Details:
#      R is a programming language that supports and checks documentation
#      for program libraries (called `packages'). The package 'roxygen2'
#      provides a tool for creating documentation from annotated source
#      code - much like 'doxygen', 'javadoc' and 'docstrings/pydoc' do.
#      And R is a free software environment for statistical computing and
#      graphics, used by people like me who start out hacking down code,
#      eventually pouring chunks of code into functions (and sometimes
#      even ending up creating and documenting packages). Along that work
#      flow you cannot use R's documentation system, let alone
#      'roxygen2', unless you have come to forge your code into a
#      package.
#      I am fully aware of the fact that 'roxygen2' is meant to document
#      packages, not single code chunks. So should you. Nevertheless I
#      feel the temptation to use 'roxygen2'-style comments in code
#      chunks that are not part of any package. And to convert them to
#      pdf for better readability.
# Warning:
#      This package writes to disk, so *never* run as superuser.
# Note:
#      This package is basically a wrapper to
#        1. 'roxygen2'. It internally creates a temporary package from
#           the code file provided (using 'utils::package.skeleton')
#           which it then passes to 'roxygen2::roxygenize'.
#        2. 'R CMD' commands run by 'callr'.
# See Also:
#      'docstring' (<URL:>)
#      also creates temporary help pages as well but using a different
#      technical approach (allowing you to view them in the 'RStudio'
#      help pane). But it creates them from python style 'docstring'-like
#      comments it then parses into 'roxygen2'. And it does not write to
#      file so far.


You can install document from github with:

if (! require("devtools")) install.packages("devtools")
devtools::install_github("fvafrCU/document", quiet = TRUE)


document 2.2.1

  • Fixed internal file parsing.
  • Exported function get_lines_between_tags().

document 2.2.0

  • Marked alter_descprition_file() as deprecated, please use CRAN package desc by Gabor Csardi instead.
    Internally, alter_descprition_file() is not used any longer. It just lingers as it was exported in version 2.1.0.
  • alter_descprition_file() now keeps whitespace, making it possible to pass newline characters, for example for the [email protected] field.

document 2.1.0

  • Fix man() to now work with RStudio.
  • Add and export a new function alter_description_file(). It serves as a replacement for the internal add_depenedencies_to_description(), and straightens the former internal clean_descprition() which used [write|read]Lines() instead of [write|read].dcf() and is now exported as clean_descprition_file().

document 2.0.0

  • document() now throws an error if the temporary package does not pass R CMD check without errors, warnings or notes.
    • Added argument 'stop_on_check_not_passing'. Set to FALSE to issue a warning() instead of throwing an error.
    • Added argument 'check_as_cran' to use the --as-cran flag with R CMD check, document() then assumes a single NOTE (on the CRAN incoming feasibility) to be okay.

document 1.2.1

  • Check for RStudio in man().
  • Fix return status of write_the_docs().

document 1.2.0

  • Enhance documenation.

document 1.1.0

  • Use the input file's basename instead of the temporary package's name as basename for the output files.
  • Only return output file paths if the according file exists.

document 1.0.0

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


3.0.1 by Andreas Dominik Cullmann, 3 days ago

Browse source code at

Authors: Andreas Dominik Cullmann [aut, cre]

Documentation:   PDF Manual  

BSD_2_clause + file LICENSE license

Imports roxygen2, callr, rcmdcheck, checkmate, rstudioapi, desc, withr

Suggests knitr, rmarkdown, devtools, RUnit, testthat, datasets, rprojroot, covr

See at CRAN