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.1.0

  • Now deleting tagged lines only if there are any.

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.3.2 by Andreas Dominik Cullmann, 4 months ago


https://gitlab.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 callr, checkmate, desc, rcmdcheck, roxygen2, rstudioapi, withr

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


Imported by rasciidoc.

Suggested by packager.


See at CRAN