Vous utilisez roxygen2 et doxygen sur le même paquet? [fermé]

91

J'ai un Rpackage qui utilise roxygen2. Il contient du Ccode /srcet je viens de commencer à travailler avec Doxygen. Existe-t-il des moyens de combiner la documentation ou d'intégrer la compilation avec roxygen2? Des «meilleures pratiques» pour savoir où placer la Cdocumentation du code?

Rechercher sur Google roxygen2 et doxygen conduit principalement à roxygen est similaire aux résultats doxygen . J'ai trouvé quelques paquets avec Doxyfiles, mais aucune organisation cohérente. Par exemple, lme4 a une inst/doc/Doxyfilesortie dans un dossier appelé en doxygendehors du lme4répertoire source. Il y a aussi un Doxyfile dans le répertoire racine de la Matrix (mais dans les versions précédentes était dedans inst. Cette documentation est également exportée en dehors du répertoire du package.

Y a-t-il une raison de ne pas inclure la Cdocumentation dans un package, ou pourquoi Doxygen est-il si rarement utilisé dans les packages R, malgré une utilisation généralisée de C?

mise à jour: voir la demande de fonctionnalité roxygen2 associée

Abe
la source
8
Cela ne répond pas à votre question, mais si vous utilisez Rcpp, vous pouvez utiliser roxygen2 pour documenter vos fonctions C ++ exportées
hadley
2
Je suppose que Doxygen n'est pas utilisé dans les packages R, car les gens ne documentent pas leur code C. Le code C ne fait presque jamais partie de l'API et du package R fourni, donc les gens ne le documentent tout simplement pas. Si vous souhaitez mettre vos documents C dans le package, générez simplement le HTML à partir d'un Makefile et placez-le dans inst /.
Gabor Csardi
1
Je ne connais pas roxygen, mais peut-être qu'il a une sortie xml, comme doxygen, et vous pouvez le combiner avec du xslt et créer un document complet à partir de cela.
Daniel Albuschat
Essayez-vous d'inclure l'entrée roxygen2 dans la sortie doxyten ou l'inverse?
Denise Skidmore

Réponses:

4

J'utilise personnellement le code suivant dans un package "dataManagement" que j'appelle dans tous mes scripts. Il contient une documentation et des exemples roxygénés. En fait, vous appelez simplement document () et faites exécuter doxygen sur le code C, dans src /. La documentation est placée dans inst / doxygen pour que votre paquet soit prêt pour CRAN.

La documentation R étant conçue pour les utilisateurs finaux R non censés regarder le code C Je n'ai pas intégré la documentation du code C dans la documentation R classique mais ce serait probablement une bonne pratique de copier la documentation C résultante sous forme de "vignette" .

    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()
    }
cmbarbu
la source
Merci! Je suppose que je ne savais pas que la solution simple était de redéfinir devtools::documentpour ajouter un appel système doxygen path/to/Doxyfile. J'ai ajouté ceci à mon package. J'ai également ajouté une demande de fonctionnalité dans le dépôt github roxygen2 @hadley
Abe
Donc - pour autant que je sache, la demande d'extraction pour cette fonctionnalité n'a pas été acceptée . Parce que je voulais néanmoins avoir un moyen pratique de créer de la documentation doxygen, j'ai créé un petit package R basé sur le code ci-dessus.
nevrome