¿Cómo se escribe la documentación del paquete? [cerrado]

StackOverflow https://stackoverflow.com/questions/3086081

Pregunta

He descubierto no es un flujo de trabajo razonable para la construcción de paquetes y escribir su documentación.

Quiero que gran parte del proceso (y la documentación) como sea posible para ser generados automáticamente.

La forma más obvia de hacerlo parece ser el uso de package.skeleton para crear los archivos de paquetes básicos, a continuación, sobrescribir el archivo mediante programación DESCRIPTION y los archivos Rd. El problema con esto es que se pierde entonces los campos generados automáticamente que asegurarse de que ha recordado a documentar todos los parámetros correctos.

Me gustaría saber como ir sobre la construcción de paquetes y escribir documentación. ¿Hay herramientas disponibles para hacer el proceso más fácil? ( roxygen parece que fue diseñada para este tipo de cosas ;?? ¿hay un buen tutorial para ello y hay otras alternativas)

¿Fue útil?

Solución

Yo uso roxygen para todos mis proyectos. Para un ejemplo, navegar por la fuente para la webvis paquete . Hadley también utiliza roxygen por su documentación (por ejemplo, ver a su lubridate paquete ).

A lo mejor de mi conocimiento, no se roxygen documentado mucho más allá de la vigette (echar un vistazo a la roxygen página de inicio ).

Roxygen es buena, ya que conduce a la programación ilustrada, en el sentido de que su documentación y el código están lado a lado. Esto también hace que el proceso de documentación un poco más fácil ya que se trabaja con todo a la vez. Definitivamente lo recomiendo, y no desarrollará ningún paquete sin que en este punto.

Dicho esto, no automatizar la documentación en el sentido de que algunas herramientas de documentación de generación hacen (por ejemplo javadoc): R interpreta roxygen comentarios que tengan el formato correcto, pero no interpreta código R en modo alguno <. / p>

En cuanto a la creación del paquete general: package-skeleton es grande para empezar. Una vez que haya creado unos paquetes puede que le resulte más fácil en el futuro sólo para crear todos los directorios, espacio de nombres, etc. con la mano. Sobre todo si se va a seguir algunas de las otras prácticas, como la inclusión de un directorio de demostración, utilizando roxygen, escribiendo una viñeta, incluyendo el código fuente o en otros idiomas.

Por último, administro mis paquetes en Eclipse (Statet); muchos de los del IDE tienen puntos de vista "proyecto" que ayuda para controlar la estructura del paquete, así que puede que quiera usar un editor más avanzado.

Otros consejos

En cuanto a los recursos roxygen, varios más han surgido desde entonces, han surgido unos cuantos más, a la cita mis propias notas :

  

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

     
Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top