Создание документации к скриптам R в формате LaTeX

Задача состоит из двух частей:

1. собственно создание документации к функции, скрипту или пакету R;
2. преобразование созданных документов в формат LaTeX.

Документация к R оформляется в виде файлов .Rd на специальном языке, синтаксис которого похож на LaTeX.

Файлы .Rd можно создавать вручную. Но существует пакет roxygen2, который создаёт их автоматически, на основе сделанных в коде комментариев.

Выглядят эти комментарии примерно так:

#' Add together two numbers
#'
#' @param x A number
#' @param y A number
#' @return The sum of \code{x} and \code{y}
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}

пример отсюда

Для того, чтобы создать Rd-документацию к этому файлу (назовём его add.R) нужно

1. создать пакет R и поместить в него add.R (несмотря на то, что это отдельный файл, а вовсе не пакет);
2. выполнить команду:

devtools::document()

Проще всего сделать это в RStudio, где создать пакет можно при помощи меню.

Другие варианты:

• package.skeleton() позволяет создать "скелет" пакета — его основные каталоги и файлы;
• devtools::create("path/to/package/pkgname")

После трансляции командой document() в папке man только что созданного пакета появится файл add.Rd:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simple.R
\name{add}
\alias{add}
\title{Add together two numbers}
\usage{
add(x, y)
}
\arguments{
\item{x}{A number}

\item{y}{A number}
}
\value{
The sum of \code{x} and \code{y}
}
\description{
Add together two numbers
}
\examples{
add(1, 1)
add(10, 1)
}

На этом первую задачу можно считать решённой. Подробности ищите в документации к пакету roxygen2.

Документы формата .Rd конвертируются в LaTeX при помощи функции Rd2latex из пакета tools (входит в базовый набор R)

Rd <- file.path("man/add.Rd")
tools::Rd2latex(Rd, out = "add.tex")

Сама функция Rd2latex генерирует только содержимое документа, но не его преамбулу:

\HeaderA{add}{Add together two numbers}{add}
%
\begin{Description}\relax
Add together two numbers
\end{Description}
%
\begin{Usage}
\begin{verbatim}
add(x, y)
\end{verbatim}
\end{Usage}
%
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A number

\item[\code{y}] A number
\end{ldescription}
\end{Arguments}
%
\begin{Value}
The sum of \code{x} and \code{y}
\end{Value}
%
\begin{Examples}
\begin{ExampleCode}
add(1, 1)
add(10, 1)
\end{ExampleCode}
\end{Examples}

Стиль оформления латеховского документа хранится в файле Rd.sty в каталоге, где установлен R. Проще всего скопировать этот файл в каталог с add.tex. Не забудьте указать пакет Rd в преамбуле документа:

\documentclass{article}
\usepackage{Rd}
\begin{document}
\input{add.tex} % файл, полученный из R
\end{document}

(естественно, если в документах нужен русский язык, то добавляем ответственные за него пакеты).

После трансляции LaTeX-ом получим:

Кроме того, существует пакет Rd2roxygen для преобразования уже имеющейся Rd-документации в формат roxygen2.

Проблема с devtools::document()

Во время работы над пакетом у меня сформировался набор вспомогательных скриптов, в частности, для создания документации. Сами эти скрипты в пакет не входили, но до поры до времени хранились в общей папке со скриптами пакета (my_package/R). Один из таких скриптов содержал вызов devtools::document().

В результате, когда я запускал devtools::document() возникал бесконечный цикл из сообщений об ошибках

Updating my_package documentation
Loading my_package
...

По-видимому, запущенный мной devtools::document() считывал скрипты, находил там devtools::document(), тот в свою очередь запускался и т.д.

Пришлось организовать отдельную папку для вспомогательных скриптов за пределами пакета. Там devtools::document() никому в пакете не мешает.

Вставка формул

Математические формулы в формате LaTeX можно вставить в документ при помощи команд:

• \eqn{latex} — для формул, размещаемых в строке (как TeX-овские $…$);
• \deqn{latex} — для выключных формул (как TeX-овские $$…$$).

Вместо latex записывается LaTeX-овская формула без символов окружения, таких как $, $$ и т.п.

Формулы можно также записывать в виде: \eqn{latex}{ascii} (и, аналогично, для \deqn). ascii — текстовая запись формулы, которая используется в текстовой версии справки.