Menggunakan roxygen2 dan doxygen dalam satu paket? [Tutup]

91

Saya memiliki Rpaket yang menggunakan roxygen2. Ini memiliki beberapa Ckode /src, dan saya baru saja mulai bekerja dengan Doxygen. Apakah ada cara untuk menggabungkan dokumentasi, atau mengintegrasikan kompilasi dengan roxygen2? Adakah "praktik terbaik" untuk tempat meletakkan Cdokumentasi kode?

Googling untuk roxygen2 dan doxygen terutama mengarah ke roxygen mirip dengan hasil doxygen . Saya telah menemukan beberapa paket dengan Doxyfiles, tetapi tidak ada organisasi yang konsisten. Misalnya, lme4 memiliki inst/doc/Doxyfilekeluaran ke folder yang disebut di doxygenluar lme4direktori sumber. Ada juga Doxyfile di direktori root Matrix (tetapi dalam rilis sebelumnya ada di inst. Dokumentasi ini juga diekspor ke luar direktori paket.

Apakah ada alasan untuk tidak menyertakan Cdokumentasi di dalam paket, atau mengapa Doxygen sangat jarang digunakan di dalam paket R, meskipun digunakan secara luas C?

update: lihat permintaan fitur roxygen2 terkait

Abe
sumber
8
Ini tidak menjawab pertanyaan Anda, tetapi jika Anda menggunakan Rcpp, Anda dapat menggunakan roxygen2 untuk mendokumentasikan fungsi C ++ yang diekspor
hadley
2
Saya kira Doxygen tidak digunakan dalam paket R, karena orang tidak mendokumentasikan kode C mereka. Kode C hampir tidak pernah menjadi bagian dari API dan paket R, jadi orang tidak mendokumentasikannya. Jika Anda ingin memasukkan dokumen C Anda ke dalam paket, cukup buat HTML dari Makefile dan letakkan di inst /.
Gabor Csardi
1
Saya tidak tahu roxygen, tapi mungkin ia memiliki beberapa keluaran xml, seperti yang dimiliki doxygen, dan Anda dapat menggabungkannya dengan beberapa xslt dan membuat dokumen lengkap dari itu.
Daniel Albuschat
Apakah Anda mencoba untuk memasukkan masukan roxygen2 ke dalam keluaran doxyten atau sebaliknya?
Denise Skidmore

Jawaban:

4

Saya pribadi menggunakan kode berikut dalam paket "dataManagement" yang saya panggil di semua skrip saya. Ini memiliki dokumentasi dan contoh roxygen. Anda sebenarnya cukup memanggil document () dan menjalankan doxygen pada kode C, di src /. Doc sudah dimasukkan ke inst / doxygen sehingga paket Anda sudah siap CRAN.

Dokumentasi R dirancang untuk pengguna akhir R yang tidak seharusnya melihat kode C. Saya tidak mengintegrasikan dokumentasi kode C dalam dokumentasi R klasik tetapi mungkin akan menjadi praktik yang baik untuk menyalin dokumentasi C yang dihasilkan sebagai "sketsa" .

    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
sumber
Terima kasih! Saya kira saya tidak menyadari bahwa solusi sederhana adalah mendefinisikan ulang devtools::documentuntuk menambahkan panggilan sistem doxygen path/to/Doxyfile. Saya telah menambahkan ini ke paket saya. Saya juga telah menambahkan permintaan fitur di repositori github roxygen2 @hadley
Abe
Jadi - sejauh yang saya pahami, permintaan tarik untuk fitur ini tidak diterima . Karena saya tetap ingin memiliki cara yang mudah untuk membuat dokumentasi doxygen, saya membuat paket R kecil berdasarkan kode di atas.
nevrome