Використання роксигену2 та доксигену в одній упаковці? [зачинено]


91

У мене є Rпакет, який використовує roxygen2. У ньому є певний Cкод /src, і я щойно почав працювати з Doxygen. Чи є способи поєднати документацію або інтегрувати компіляцію з roxygen2? Будь-які "найкращі практики" щодо того, де розмістити Cдокументацію про код?

Гуглиння за вмістом кисню2 та кисню в першу чергу призводить до кисню, подібне до результатів дії кисню . Я знайшов кілька пакетів з Doxyfiles, але жодної послідовної організації. Наприклад, lme4 має inst/doc/Doxyfileвихід у папку, що називається doxygenпоза lme4вихідним каталогом. У кореневому каталозі Матриці також є файл Doxy (але в попередніх випусках він був inst. Ця документація також експортується за межі каталогу пакунків.

Чи є якісь причини не включати Cдокументацію всередину пакету, або чому кисень так рідко використовується в пакетах R, незважаючи на широке використання C?

оновлення: див. відповідний запит на функцію roxygen2


8
Це не відповідає на ваше запитання, але якщо ви використовуєте Rcpp, ви можете використовувати roxygen2 для документування експортованих функцій C ++
hadley

2
Думаю, кисень не використовується в пакунках R, оскільки люди не документують свій код С. Код С майже ніколи не є частиною пакету API і R, тому люди просто не документують його. Якщо ви хочете помістити ваші документи C в пакет, просто згенеруйте HTML із файлу Make і помістіть його в inst /.
Gabor Csardi 07

1
Я не знаю roxygen, але, можливо, він має певний результат xml, як і doxygen, і ви можете поєднати його з деяким xslt і створити з нього повний документ.
Даніель Альбушат,

Ви намагаєтесь включити введення roxygen2 у вихід doxyten чи навпаки?
Деніз Скідмор

Відповіді:


4

Я особисто використовую наступний код у пакеті "dataManagement", який я викликаю у всіх своїх сценаріях. У ньому є киснева документація та приклади. Ви насправді просто викликаєте document () і запускаєте doxygen на коді C в src /. Документ поміщається в inst / doxygen, щоб ваш пакет був готовим до CRAN.

Документація R, розроблена для кінцевих користувачів R, не повинна розглядати код C, я не інтегрував документацію коду C в класичну документацію R, але, мабуть, було б гарною практикою скопіювати отриману документацію C як "віньєтку" .

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

Дякую! Здається, я не розумів, що простим рішенням було перевизначення devtools::documentдля додавання системного виклику doxygen path/to/Doxyfile. Я додав це у свій пакет. Я також додав запит на функцію до репозиторію roxygen2 github @hadley
Abe,

Отже - наскільки я розумію, запит на витяг для цієї функції не був прийнятий . Оскільки я все-таки хотів мати зручний спосіб створення документації про кисень, я створив невеликий пакет R на основі коду вище.
невром
Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.