Aynı pakette roxygen2 ve doxygen kullanıyor musunuz? [kapalı]


91

RKullanan bir paketim var roxygen2. İçinde bir Ckod /srcvar ve Doxygen ile çalışmaya başladım. Belgeleri birleştirmenin veya derlemeyi roxygen2 ile entegre etmenin herhangi bir yolu var mı? CKod belgelerini nereye koyacağınıza dair herhangi bir "en iyi uygulama" ?

Oksijen2 ve doxygen için googling, öncelikle roxygen'e yol açar , doxygen sonuçlarına benzer . Doxyfiles ile birkaç paket buldum, ancak tutarlı bir organizasyon yok. Örneğin, lme4, kaynak dizinin dışında inst/doc/Doxyfileadı verilen bir klasöre çıktı verir . Ayrıca, Matrix'in kök dizininde bir Doxyfile vardır (ancak önceki sürümlerde idi . Bu belgeler de paket dizininin dışına verilir.doxygenlme4inst

CBelgeleri bir paketin içine dahil etmemek için herhangi bir sebep var mı veya Doxygen'in yaygın kullanımına rağmen R paketlerinde neden bu kadar seyrek olarak kullanılıyor C?

güncelleme: ilgili roxygen2 özelliği isteğine bakın


8
Bu, sorunuzu yanıtlamaz, ancak Rcpp kullanıyorsanız, dışa
aktardığınız

2
Sanırım Doxygen R paketlerinde kullanılmıyor çünkü insanlar C kodunu belgelemiyorlar. C kodu neredeyse hiçbir zaman API ve R paketinin bir parçası değildir, bu nedenle insanlar bunu belgelemez. C belgelerinizi pakete koymak istiyorsanız, HTML'yi bir Makefile'dan oluşturun ve inst / içine koyun.
Gabor Csardi

1
Roxygen'i bilmiyorum ama belki de doxygen'in sahip olduğu gibi bazı xml çıktıları vardır ve bunu bir miktar xslt ile birleştirebilir ve bundan tam bir belge oluşturabilirsiniz.
Daniel Albuschat

Doxyten çıkışına roxygen2 girişini dahil etmeye mi çalışıyorsunuz yoksa tam tersi mi?
Denise Skidmore

Yanıtlar:


4

Kişisel olarak aşağıdaki kodu, tüm komut dosyalarımda çağırdığım "dataManagement" paketinde kullanıyorum. Roxygen belgelerine ve örneklerine sahiptir. Aslında basitçe document () işlevini çağırırsınız ve doxygen'in src / içinde C kodunda çalıştırılmasını sağlarsınız. Belge, inst / doxygen'e yerleştirilir, böylece paketiniz CRAN için hazırdır.

R son kullanıcıları için tasarlanan R dokümantasyonu , C koduna bakmamalı. C kodu dokümantasyonunu klasik R dokümantasyonuna entegre etmedim, ancak sonuçta ortaya çıkan C dokümantasyonunu bir "vinyet" olarak kopyalamak muhtemelen iyi bir uygulama olacaktır. .

    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()
    }

Teşekkürler! Sanırım basit çözümün devtools::documentbir sistem çağrısı eklemek için yeniden tanımlamak olduğunu fark etmemiştim doxygen path/to/Doxyfile. Bunu paketime ekledim. Ayrıca roxygen2 github deposuna bir özellik isteği ekledim @hadley
Abe

Yani - anladığım kadarıyla bu özellik için çekme talebi kabul edilmedi . Yine de doxygen dokümantasyonu oluşturmanın uygun bir yolunu istediğim için, yukarıdaki koda dayalı küçük bir R paketi oluşturdum .
nevrome
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.