Saya memiliki R
paket yang menggunakan roxygen2
. Ini memiliki beberapa C
kode /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 C
dokumentasi 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/Doxyfile
keluaran ke folder yang disebut di doxygen
luar lme4
direktori 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 C
dokumentasi di dalam paket, atau mengapa Doxygen sangat jarang digunakan di dalam paket R, meskipun digunakan secara luas C
?
update: lihat permintaan fitur roxygen2 terkait
Jawaban:
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() }
sumber
devtools::document
untuk menambahkan panggilan sistemdoxygen path/to/Doxyfile
. Saya telah menambahkan ini ke paket saya. Saya juga telah menambahkan permintaan fitur di repositori github roxygen2 @hadley