Verwenden Sie roxygen2 und doxygen im selben Paket? [geschlossen]

91

Ich habe ein RPaket, das verwendet roxygen2. Es enthält CCode /srcund ich habe gerade angefangen, mit Doxygen zu arbeiten. Gibt es Möglichkeiten, die Dokumentation zu kombinieren oder das Kompilieren mit roxygen2 zu integrieren? Gibt es "Best Practices" für das Ablegen der CCodedokumentation?

Das Googeln nach Roxygen2 und Doxygen führt hauptsächlich zu Roxygen und ähnelt den Ergebnissen von Doxygen . Ich habe einige Pakete mit Doxyfiles gefunden, aber keine konsistente Organisation. Zum Beispiel hat lme4 inst/doc/Doxyfilein einen Ordner ausgegeben, der doxygenaußerhalb des lme4Quellverzeichnisses aufgerufen wird . Es gibt auch eine Doxy-Datei im Stammverzeichnis der Matrix (aber in früheren Versionen war in inst. Diese Dokumentation wird auch außerhalb des Paketverzeichnisses exportiert.

Gibt es einen Grund, die CDokumentation nicht in ein Paket aufzunehmen, oder warum wird Doxygen in R-Paketen trotz der weit verbreiteten Verwendung von so selten verwendet C?

Update: Siehe entsprechende Roxygen2-Funktionsanforderung

Abe
quelle
8
Dies beantwortet Ihre Frage nicht, aber wenn Sie Rcpp verwenden, können Sie roxygen2 verwenden, um Ihre exportierten C ++
hadley
2
Ich denke, Doxygen wird in R-Paketen nicht verwendet, weil die Leute ihren C-Code nicht dokumentieren. C-Code ist fast nie Teil der API und des R-Pakets, daher wird er nur nicht dokumentiert. Wenn Sie Ihre C-Dokumente in das Paket einfügen möchten, generieren Sie einfach den HTML-Code aus einem Makefile und fügen Sie ihn in inst / ein.
Gabor Csardi
1
Ich kenne roxygen nicht, aber vielleicht hat es eine XML-Ausgabe, wie es doxygen getan hat, und Sie können es mit etwas xslt kombinieren und daraus ein vollständiges Dokument erstellen.
Daniel Albuschat
Versuchen Sie, die Eingabe von roxygen2 in die Ausgabe von doxyten einzubeziehen oder umgekehrt?
Denise Skidmore

Antworten:

4

Ich persönlich verwende den folgenden Code in einem "dataManagement" -Paket, das ich in allen meinen Skripten aufrufe. Es enthält Sauerstoffdokumentation und Beispiele. Sie rufen tatsächlich einfach document () auf und haben doxygen auf dem C-Code in src / ausgeführt. Das Dokument wird in inst / doxygen abgelegt, damit Ihr Paket CRAN-fähig ist.

Die R-Dokumentation wurde für R- Endbenutzer entwickelt, die sich nicht mit dem C-Code befassen sollten. Ich habe die C-Code-Dokumentation nicht in die klassische R-Dokumentation integriert, aber es wäre wahrscheinlich eine gute Praxis, die resultierende C-Dokumentation als "Vignette" zu kopieren. .

    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
quelle
Vielen Dank! Ich glaube, ich wusste nicht, dass die einfache Lösung darin bestand, neu zu definieren devtools::document, um einen Systemaufruf hinzuzufügen doxygen path/to/Doxyfile. Ich habe dies zu meinem Paket hinzugefügt. Ich habe auch eine Feature-Anfrage im roxygen2 Github-Repository @hadley
Abe
Soweit ich weiß, wurde die Pull-Anfrage für diese Funktion nicht akzeptiert . Da ich dennoch eine bequeme Möglichkeit zum Erstellen von Sauerstoffdokumentation haben wollte, habe ich ein kleines R-Paket basierend auf dem obigen Code erstellt.
Nevrom