romualfons - ¿Cómo escribes la documentación de tu paquete?
romuald seo (2)
No he descubierto un flujo de trabajo adecuado para crear paquetes y escribir su documentación.
Quiero que todo el proceso (y la documentación) sea posible para que se genere automáticamente.
La forma obvia de hacer esto parece ser usar package.skeleton para crear los archivos básicos del paquete, y luego sobrescribir mediante programación el archivo DESCRIPTION y los archivos Rd . El problema con esto es que luego pierdes los campos generados automáticamente que aseguran haber recordado documentar todos los parámetros correctos.
Me gustaría saber cómo vas construyendo paquetes y escribiendo documentación. ¿Existen herramientas disponibles para facilitar el proceso? ( roxygen parece que fue diseñado para este tipo de cosas; ¿hay un buen tutorial para él? ¿Y hay alternativas?)
Con respecto a los recursos de roxygen, han surgido varios más, han surgido algunos más, para citar mis propias notas :
A menudo, cuando busco en Google Roxygen o Roxygen2 tengo problemas para encontrar documentación. Aquí hay una recopilación de algunos recursos clave:
Hadley Wickham tiene una gran introducción a las características principales de Roxygen 2
RStudio tiene notas sobre la ejecución de Roxygen
Uso roxygen para todos mis proyectos. Para un ejemplo, busque la fuente del paquete webvis . Hadley también utiliza roxygen para su documentación (por ejemplo, consulte su paquete de lubricación ).
Según mi conocimiento, roxygen no está documentado mucho más allá de la vigette (eche un vistazo a la página de inicio de roxygen ).
Roxygen es bueno porque conduce a una programación alfabetizada, en el sentido de que su documentación y código están uno al lado del otro. 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 él en este punto.
Dicho esto, no automatiza la documentación en el sentido de que lo hacen algunas herramientas de generación de documentación (por ejemplo, javadoc): roxygen interpreta los comentarios de R que están correctamente formateados, pero no interpreta el código R de ninguna manera.
Con respecto a la creación del paquete en general: el package-skeleton es ideal para empezar. Una vez que haya creado algunos paquetes, puede que le resulte 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 código fuente en otros idiomas.
Por último, administro mis paquetes en Eclipse (StatET); muchos de los IDE tienen vistas de "proyecto" que ayudan a administrar la estructura del paquete, por lo que es posible que también desee utilizar un editor más avanzado.