¿Usa roxygen2 y doxygen en el mismo paquete? [cerrado]


91

Tengo un Rpaquete que usa roxygen2. Tiene algo de Ccódigo /srcy acabo de empezar a trabajar con Doxygen. ¿Hay alguna forma de combinar la documentación o integrar la compilación con roxygen2? ¿Alguna "mejor práctica" sobre dónde colocar la Cdocumentación del código?

Buscar en Google roxygen2 y doxygen conduce principalmente a roxygen es similar a los resultados de doxygen . Encontré algunos paquetes con Doxyfiles, pero no una organización consistente. Por ejemplo, lme4 tiene inst/doc/Doxyfilesalida a una carpeta llamada doxygenfuera del lme4directorio de origen. También hay un Doxyfile en el directorio raíz de Matrix (pero en versiones anteriores estaba en inst. Esta documentación también se exporta fuera del directorio del paquete.

¿Hay alguna razón para no incluir la Cdocumentación dentro de un paquete, o por qué Doxygen se usa con tanta poca frecuencia dentro de los paquetes R, a pesar del uso generalizado de C?

actualización: consulte la solicitud de función roxygen2 relacionada


8
Esto no responde a su pregunta, pero si usa Rcpp, puede usar roxygen2 para documentar sus funciones C ++ exportadas
hadley

2
Supongo que Doxygen no se usa en paquetes R, porque la gente no documenta su código C. El código C casi nunca forma parte de la API y el paquete R lo proporciona, por lo que la gente simplemente no lo documenta. Si desea poner sus documentos C en el paquete, simplemente genere el HTML a partir de un Makefile y colóquelo en inst /.
Gabor Csardi

1
No sé roxygen, pero tal vez tenga algo de salida xml, como lo tiene doxygen, y puedes combinarlo con algo de xslt y crear un documento completo a partir de eso.
Daniel Albuschat

¿Está intentando incluir la entrada de roxygen2 en la salida de doxyten o al revés?
Denise Skidmore

Respuestas:


4

Yo personalmente uso el siguiente código en un paquete de "gestión de datos" que llamo en todos mis scripts. Tiene documentación y ejemplos de roxygen. En realidad, simplemente llama a document () y hace que doxygen se ejecute en el código C, en src /. El documento se coloca en inst / doxygen para que su paquete esté listo para CRAN.

La documentación de R está diseñada para usuarios finales de R que se supone que no deben mirar el código C. No integré la documentación del código C en la documentación R clásica, pero probablemente sería una buena práctica copiar la documentación C resultante como una "viñeta". .

    library("testthat")
    library("devtools")

    #' @title Replace a value for a given tag on file in memory
    #' @description Scan the lines and change the value for the named tag if one line has this tag, 
    #'    add a line at the end if no line has this tag and return a warning if several lines
    #'    matching the tag
    #' @param fileStrings A vector with each string containing a line of the file
    #' @param tag The tag to be searched for 
    #' @param newVal The new value for the tag
    #' @return The vector of strings with the new value
    #' @examples
    #' fakeFileStrings <- c("Hello = world","SURE\t= indeed","Hello = you")
    #' 
    #' expect_warning(ReplaceTag(fakeFileStrings,"Hello","me"))
    #' 
    #' newFake <- ReplaceTag(fakeFileStrings,"SURE","me")
    #' expect_equal(length(newFake), length(fakeFileStrings))
    #' expect_equal(length(grep("SURE",newFake)), 1)
    #' expect_equal(length(grep("me",newFake)), 1)
    #' 
    #' newFake <- ReplaceTag(fakeFileStrings,"Bouh","frightened?")
    #' expect_equal(length(newFake), length(fakeFileStrings)+1)
    #' expect_equal(length(grep("Bouh",newFake)), 1)
    #' expect_equal(length(grep("frightened?",newFake)), 1)
    ReplaceTag <- function(fileStrings,tag,newVal){
        iLine <- grep(paste0("^",tag,"\\>"),fileStrings)
        nLines <- length(iLine)
        if(nLines == 0){
            line <- paste0(tag,"\t= ",newVal)
            iLine <- length(fileStrings)+1
        }else if (nLines > 0){
            line <- gsub("=.*",paste0("= ",newVal),fileStrings[iLine])
            if(nLines >1){
                warning(paste0("File has",nLines,"for key",tag,"check it up manually"))
            }
        }
        fileStrings[iLine] <- line
        return(fileStrings)
    }
    #' Prepares the R package structure for use with doxygen
    #' @description Makes a configuration file in inst/doxygen
    #'     and set a few options: 
    #'     \itemize{
    #'        \item{EXTRACT_ALL = YES}
    #'        \item{INPUT = src/}
    #'        \item{OUTPUT_DIRECTORY = inst/doxygen/}
    #'     }
    #' @param rootFolder The root of the R package
    #' @return NULL
    #' @examples 
    #' \dontrun{
    #' DoxInit()
    #' }
    #' @export
    DoxInit <- function(rootFolder="."){
        doxyFileName <- "Doxyfile"
        initFolder <- getwd()
        if(rootFolder != "."){
            setwd(rootFolder)
        }
        rootFileYes <- length(grep("DESCRIPTION",dir()))>0
        # prepare the doxygen folder
        doxDir <- "inst/doxygen"
        if(!file.exists(doxDir)){
            dir.create(doxDir,recursive=TRUE)
        }
        setwd(doxDir)

        # prepare the doxygen configuration file
        system(paste0("doxygen -g ",doxyFileName))
        doxyfile <- readLines("Doxyfile")
        doxyfile <- ReplaceTag(doxyfile,"EXTRACT_ALL","YES")
        doxyfile <- ReplaceTag(doxyfile,"INPUT","src/")
        doxyfile <- ReplaceTag(doxyfile,"OUTPUT_DIRECTORY","inst/doxygen/")
        cat(doxyfile,file=doxyFileName,sep="\n")
        setwd(initFolder)
        return(NULL)
    }

    #' devtools document function when using doxygen
    #' @description Overwrites devtools::document() to include the treatment of 
    #'    doxygen documentation in src/
    #' @param doxygen A boolean: should doxygen be ran on documents in src?
    #'     the default is TRUE if a src folder exist and FALSE if not
    #' @return The value returned by devtools::document()
    #' @example
    #' \dontrun{
    #' document()
    #' }
    #' @export
    document <- function(doxygen=file.exists("src")){
        if(doxygen){
            doxyFileName<-"inst/doxygen/Doxyfile"
            if(!file.exists(doxyFileName)){
                DoxInit()
            }
            system(paste("doxygen",doxyFileName))
        }
        devtools::document()
    }

¡Gracias! Supongo que no me di cuenta de que la solución simple era redefinir devtools::documentpara agregar una llamada al sistema doxygen path/to/Doxyfile. He agregado esto a mi paquete. También agregué una solicitud de función en el repositorio de github de roxygen2 @hadley
Abe

Por lo que tengo entendido, no se aceptó la solicitud de extracción para esta función . Como, no obstante, quería tener una forma conveniente de crear documentación de doxygen, creé un pequeño paquete R basado en el código anterior.
Nevrome
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.