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

Lesezeit: 5 Minuten

Abes Benutzer-Avatar
Abe

ich habe ein R Paket, das verwendet roxygen2. Es hat einige C Code ein /srcund ich habe gerade angefangen, mit zu arbeiten Doxygen. Gibt es Möglichkeiten, die Dokumentation zu kombinieren oder das Kompilieren mit roxygen2 zu integrieren? Irgendwelche “Best Practices” für die Platzierung der C Code-Dokumentation?

Das Googeln nach roxygen2 und doxygen führt in erster Linie zu roxygen ist ähnlich wie doxygen Ergebnisse. Ich habe ein paar Pakete mit Doxyfiles gefunden, aber keine einheitliche Organisation. Zum Beispiel, lme4 hat inst/doc/Doxyfile Ausgabe in einen Ordner namens doxygen außerhalb von lme4 Quellverzeichnis. 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 C Dokumentation innerhalb eines Pakets, oder warum Doxygen trotz weit verbreiteter Verwendung so selten in R-Paketen verwendet wird C?

aktualisieren: siehe verwandt roxygen2 Funktionsanfrage

  • Dies beantwortet Ihre Frage nicht, aber wenn Sie Rcpp verwenden, können Sie roxygen2 verwenden, um Ihre exportierten C++-Funktionen zu dokumentieren

    – hadley

    22. Dezember 2013 um 16:45 Uhr


  • 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, sodass die Leute ihn einfach nicht dokumentieren. 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

    7. Juli 2014 um 3:08 Uhr

  • Ich kenne roxygen nicht, aber vielleicht hat es eine XML-Ausgabe, wie doxygen, und Sie können es mit etwas xslt kombinieren und daraus ein vollständiges Dokument erstellen.

    – Daniel Albuschat

    13. Dezember 2014 um 7:04 Uhr

  • Versuchen Sie, die roxygen2-Eingabe in die doxyten-Ausgabe einzufügen oder umgekehrt?

    – Denise Skidmore

    16. Januar 2015 um 20:40 Uhr

Benutzeravatar von cmbarbu
cmbarbu

Ich persönlich verwende den folgenden Code in einem “dataManagement”-Paket, das ich in allen meinen Skripten aufrufe. Es hat Roxygen-Dokumentation und Beispiele. Sie rufen eigentlich einfach document() auf und lassen doxygen auf dem C-Code in src/ laufen. Das Dokument wird in inst/doxygen abgelegt, damit Ihr Paket für CRAN bereit ist.

Die für R konzipierte R-Dokumentation Endverbraucher soll nicht auf den C-Code schauen 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()
    }

  • 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 hinzugefügt Funktionsanfrage im roxygen2-Github-Repository @hadley

    – Abe

    10. März 2015 um 17:20 Uhr


  • Also – soweit ich es verstehe, war die Pull-Anfrage für diese Funktion nicht akzeptiert. Da ich trotzdem eine bequeme Möglichkeit haben wollte, eine doxygen-Dokumentation zu erstellen, habe ich eine kleine R-Paket basierend auf dem obigen Code.

    – Nevrom

    8. April 2017 um 11:32 Uhr


1420070cookie-checkVerwenden Sie roxygen2 und doxygen im selben Paket? [closed]

This website is using cookies to improve the user-friendliness. You agree by using the website further.

Privacy policy