matt-dray / snorkel

:diving_mask::label: R package: RStudio Addin to help document functions with {roxygen2}

{snorkel}

An R package containing an RStudio Addin to help you insert R Documentation (Rd) markup to your package's function documentation.

You put a snorkel in your mouth to help you breathe oxygen; you put a {snorkel} in your Addins to help you prepare documentation with {roxygen2}.

Install

Install from Github with:

install.packages("remotes")  # if not already installed
remotes::install_github("matt-dray/snorkel")

Use

To use the Addin:

1. Select some text in your function documentation to which you'd like to apply Rd markup (e.g. bold, italics), or place the cursor where you'd like to insert an Rd skeleton (i.e. the functions that insert lists)
2. Click the 'RStudio Addins' dropdown at the top of the RStudio IDE
3. Scroll/search for 'SNORKEL' and click the function you want

For speed, you can also search for the functions from the RStudio command palette or create custom RStudio keyboard shortcuts.

So, for example, you could highlight the word bold in #' This is bold and select the 'Format Bold' function from the Addin, resulting in #' This is \strong{bold}.

Special cases are ‘Link To Function (Another Package)’ and ‘Link To Function (Another Package, Show Name)’. Both need as input the package name and the function name that you’re linking to, which you should supply in the form 'package::function'.

Help

For help with {snorkel} functions, take a look at the reference page on the package website, or in your R console type ? followed by the function name for its documentation.

Demo

Code of Conduct

Please note that the {snorkel} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

snorkel's Issues

Provide functions for Markdown support

You can use Markdown in roxygen function documentation, as per the {roxygen2} guidance.

Some of these are like normal Markdown, like backticks for code, but others are less obvious, like the [text][ref] format.

Perhaps use different function suffixes for the md vs rd approaches, like md_*() and roxy_*() or whatever.

Would probably want a new section in the reference tab of the pkgdown site as well.

Clarify tag nomenclature

Ensure the correct wording is used throughout the package. Like @details is a roxygen tag and\emph{} would be an Rd tag, right? Check this.

Expand the help files

In {quartostamp} I added to @details the exact text that would be placed in the document and to @sources a link to the guidance docs online (e.g. for stamp_columns()).

Should do the same here.

Missing name from link to function in another package

Using rd_fn_other_pkg() on package::function results in \code{\link[package]{function}} as expected.

But if you don't highlight any text before using the function, you get: \code{\link[}}, i.e. ]{ are missing from the middle.

Perhaps want a separate print statement when text hasn't first been selected.