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

Introduction

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 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: https://cran.r-project.org/package=docstring>)
#      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.

Installation

You can install document from github with:

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

News

document 3.0.2

  • Patched failing "CRAN Package Check Results for Package document".
  • Skipping most tests on CRAN.

document 3.0.0

  • Added a fix to make the evaluation of whether or not/how we pass R CMD check more stable by using rcmdcheck internally. This causes the check_result-item of the list returned by document() to change: it is now the return value of rcmdcheck::rcmdcheck() instead of the return value of callr::rcmd_safe("check", ...).
  • The (internal) functions
    • is_Rd_file
    • display_Rd
    • fake_package
    • check_package
    • sort_unlocale
    • alter_description_file
    • Rd_txt_RUnit are not exported any longer.

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.

install.packages("document")

3.0.2 by Andreas Dominik Cullmann, 2 months ago


https://github.com/fvafrCU/document


Browse source code at https://github.com/cran/document


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