¿Cómo se escribe la documentación de su paquete?

Question

No he encontrado un flujo de trabajo sensato para crear paquetes y escribir su documentación.

Quiero que la mayor parte del proceso (y la documentación) posible se genere automáticamente.

La forma obvia de hacer esto parece ser usar package.skeleton para crear los archivos de paquete básico, luego sobrescribir el archivo DESCRIPTION y los archivos Rd mediante programación. El problema con esto es que luego pierde los campos generados automáticamente que le aseguran que se acordó de documentar todos los parámetros correctos.

Me gustaría saber cómo usted ir sobre la construcción de paquetes y escribir la documentación. ¿Hay herramientas disponibles para facilitar el proceso? (roxygen parece que fue diseñado para este tipo de cosas, ¿hay un buen tutorial para ello? Y ¿hay alguna alternativa?)

Answer 1

Uso roxygen para todos mis proyectos. Por ejemplo, explore la fuente para the webvis package. Hadley también usa roxygen para su documentación (por ejemplo, vea su lubridate package).

Por lo que yo sé, roxygen no está documentado mucho más allá de la vigette (eche un vistazo a the roxygen homepage).

Roxygen es bueno porque conduce a la programación alfabetizada, en el sentido de que su documentación y código están en paralelo. Esto también hace que el proceso de documentación sea un poco más fácil ya que está trabajando con todo a la vez. Definitivamente lo recomiendo, y no desarrollaré ningún paquete sin este en este momento.

Dicho esto, no automatiza la documentación en el sentido de que algunas herramientas de generación de documentación sí lo hacen (por ejemplo, javadoc): roxygen interpreta comentarios R que están formateados correctamente, pero no interpreta el código R de ninguna manera.

En cuanto a la creación del paquete en general: package-skeleton es ideal para principiantes. Una vez que haya creado algunos paquetes, le resultará más fácil en el futuro simplemente crear todos los directorios, NAMESPACE, etc. a mano. Especialmente si va a seguir algunas de las otras prácticas, como incluir un directorio de demostración, usar roxygen, escribir una viñeta o incluir el código fuente en otros idiomas.

Por último, administro mis paquetes en Eclipse (StatET); muchos de los IDE tienen vistas de "proyectos" que ayudan a administrar la estructura del paquete, por lo que es posible que también desee utilizar un editor más avanzado.

Answer 2

respecta a los recursos roxygen, varios más han surgido desde entonces, han surgido unos cuantos más, para citar my own notes:

A menudo, cuando I Google Roxygen o Roxygen2 que tienen problemas para encontrar documentación.He aquí una recopilación de algunos recursos clave:

• Hadley Wickham tiene una gran introduction to core features of Roxygen 2

• Hay several vignettes listed on the Cran site for Roxygen 2

• rstudio tiene notas en running Roxygen

• roxygen2 package source code on github