diff --git a/DESCRIPTION b/DESCRIPTION index 53b76c9..acb1ddb 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,14 +1,15 @@ Package: goxygen Type: Package Title: Documentation package for modular GAMS code -Version: 0.10.0 -Date: 2018-09-06 +Version: 0.11.0 +Date: 2018-09-07 Authors@R: c(person("Jan Philipp", "Dietrich", email = "dietrich@pik-potsdam.de", role = c("aut","cre"))) Description: A collection of tools which allow to manipulate and analyze code. Imports: pander, stringi, lucode URL: https://github.com/pik-piam/goxygen, https://doi.org/10.5281/? BugReports: https://github.com/pik-piam/goxygen/issues License: BSD_2_clause + file LICENSE +Encoding: UTF-8 LazyData: no RoxygenNote: 6.1.0 -ValidationKey: 1778000 +ValidationKey: 1955910 diff --git a/NAMESPACE b/NAMESPACE index 939fc37..2f9f3e2 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -6,6 +6,7 @@ export(buildTEX) export(extractDocumentation) export(gamsequation2tex) export(goxygen) +export(readConf) importFrom(lucode,codeCheck) importFrom(lucode,modules_interfaceplot) importFrom(pander,pandoc.table.return) @@ -16,4 +17,5 @@ importFrom(stringi,stri_replace_all_fixed) importFrom(stringi,stri_replace_all_regex) importFrom(stringi,stri_replace_first_fixed) importFrom(stringi,stri_replace_first_regex) +importFrom(utils,packageVersion) importFrom(utils,tail) diff --git a/R/buildHTML.R b/R/buildHTML.R index b90388f..0f6ce51 100644 --- a/R/buildHTML.R +++ b/R/buildHTML.R @@ -10,13 +10,19 @@ #' @param mdfolder path to the markdown folder to be used as source #' @param literature path to a bibliography, if available (will be ignored #' if file does not exist) +#' @param goxygen_conf path to a goxygen configuration file (will be ignored if file does not exist). The file +#' can be used to supply additional information about the model such as name or version number. +#' Allowed settings are: Name (name of the model) and Version (model version). +#' Entries are supplied in the format "Name: content", each entry must be a single line. #' @param supplementary a vector of files and/or folders required for the conversion #' (e.g. an images subdirectory with figures to be shown in the documents) +#' @param addHTML character vector with HTML code which should be added to the body of each HTML file. #' @author Jan Philipp Dietrich #' @seealso \code{\link{goxygen}}, \code{\link{buildPDF}} +#' @importFrom utils packageVersion #' @export -buildHTML <- function(folder="html", mdfolder="markdown", literature="literature.bib", supplementary=NULL) { +buildHTML <- function(folder="html", mdfolder="markdown", literature="literature.bib", goxygen_conf="goxygen.conf", supplementary=NULL, addHTML=NULL) { message("Start HTML creation...") check_pandoc() files <- list.files(mdfolder,pattern="*.md",full.names = TRUE) @@ -25,10 +31,54 @@ buildHTML <- function(folder="html", mdfolder="markdown", literature="literature file.copy(system.file("templates","template.css",package="goxygen"),paste0(folder,"/template.css")) ref <- tempfile() returnReferences(moduleNames,paste0(moduleNames,".htm"),ref, level=2) + + returnHTMLNav <- function(names, targets, id="TOCL") { + out <- paste0('
','','
') + return(out) + } + + addMainHeaderHTML <- function(goxygen_conf) { + cfg <- readConf(goxygen_conf) + + if(file.exists("images/logo.png")) { + logo <- ' ' + } else { + logo <- NULL + } + + if(!is.null(cfg$Version)) { + version <- paste0(" | Version ",cfg$Version) + } else { + version <- NULL + } + + out <- c('
', + '
', + logo, + paste0('

Model Documentation

',version,'

'), + paste0(' created with goxygen ',packageVersion("goxygen"),''), + '
') + return(out) + } + + addHTML <- c(addHTML,addMainHeaderHTML(goxygen_conf),returnHTMLNav(moduleNames, paste0(moduleNames,".htm"))) + bib <- ifelse(file.exists(literature),paste0("--bibliography=",literature),"") for(m in moduleNames) { - system(paste0("pandoc ",mdfolder,"/",m,".md ",ref," -o ",folder,"/",m, - ".htm --css template.css ",bib," --mathjax --standalone --metadata link-citations=true --metadata title=",m)) + ofile <- paste0(folder,"/",m,".htm") + system(paste0("pandoc ",mdfolder,"/",m,".md ",ref," -o ",ofile, + " --css template.css ",bib," --toc --mathjax --standalone --metadata link-citations=true --metadata title=",m)) + # Add additional code to html file + if(!is.null(addHTML)) { + html <- readLines(ofile) + cut <- which(html=="") + html <- c(html[1:cut],addHTML,html[cut+1:(length(html))]) + writeLines(html,ofile) + } } unlink(ref) for(elem in supplementary) file.copy(elem,folder,recursive = TRUE, overwrite = TRUE) diff --git a/R/goxygen.R b/R/goxygen.R index 6825910..da7b4d0 100644 --- a/R/goxygen.R +++ b/R/goxygen.R @@ -20,6 +20,17 @@ #' \item @stop everything following will be ignored until the next identifier is mentioned again. Useful #' to stop a section #' } +#' +#' You can supply additional information via a file named goxygen.conf stored in the doc folder of your model. +#' Currently it can contain model namd and model version. The file should be formatted +#' as follows: +#' +#' \code{Model: MyModel} \cr +#' \code{Version: 1.2.3-beta} +#' +#' In addition you can store a model logo (100px height) as \code{doc/images/logo.png} which then will be used in the +#' HTML version of the documentation. +#' #' @param path path to the model to be documented #' @param docfolder folder the documentation should be written to relative to model folder #' @param cache Boolean to allow read data from existing cache file diff --git a/R/readConf.R b/R/readConf.R new file mode 100644 index 0000000..f72f07a --- /dev/null +++ b/R/readConf.R @@ -0,0 +1,22 @@ +#' readConf +#' +#' Read goxygen configuration file +#' @param goxygen_conf path to a goxygen configuration file (will be ignored if file does not exist). The file +#' can be used to supply additional information about the model such as name or version number. +#' Allowed settings are: Name (name of the model), Version (model version) and Logo (path to a model logo). +#' Entries are supplied in the format "Name: content", each entry must be a single line. +#' @author Jan Philipp Dietrich +#' @seealso \code{\link{goxygen}}, \code{\link{buildHTML}} +#' @export + +readConf <- function(goxygen_conf) { + if(!file.exists(goxygen_conf)) return(NULL) + a <- readLines(goxygen_conf) + pattern <- "^([^:]*): (.*)$" + #extract only settings from lines which follow the pattern: + a <- grep(pattern,a,value=TRUE) + item <- sub(pattern,"\\1",a) + value <- sub(pattern,"\\2",a) + names(value) <- item + return(as.list(value)) +} \ No newline at end of file diff --git a/inst/templates/template.css b/inst/templates/template.css index b7fec3d..6fe4e1c 100644 --- a/inst/templates/template.css +++ b/inst/templates/template.css @@ -23,18 +23,75 @@ summary { display: block; } -#TOC { float: right; border: 1px solid gray; background-color: #F2F2F2; padding-right: 5px; margin-left: 5px;} +#TOCL { + position: absolute; + top: 100px; + border: 0px solid gray; + background-color: #F2F2F2; + padding-right: 20px; + transform: translate(calc(-100% - 4em),0); + z-index: -1; +} + +#TOC { + position: absolute; + top: 100px; + border: 0px solid gray; + background-color: #F2F2F2; + padding-right: 20px; + transform: translate(48em,0); + z-index: -1; +} + +#logo { + float: left; + margin-right: 10px; +} + +#mainheader { + position: absolute; + padding: 0; + top: 0; + width: 44em; + height: 100px; + background-color: #F2F2F2; +} + +#mainheaderbox { + position: absolute; + top: 0; + left: 0; + width: 100%; + height: 100px; + background-color: #F2F2F2; +} + +#mainheadertext { + margin-bottom:0; + padding:0; +} + +#mainheadertitle { + display: inline-block; + margin-bottom:0; + margin-right:8px; +} + +#mainheaderversion { + display: inline-block; + margin-bottom:0; +} /** * Reduce font size of formulas to same font size as text */ -span.math.inline { +/*.inline { font-size: 85%; } -span.math.display { +.display { font-size: 85%; -} +}*/ /** @@ -440,5 +497,6 @@ display: inline; html, body{ margin: auto; padding-right: 1em; padding-left: 1em; + margin-top: 110px; max-width: 44em; color:black;}*:not('#mkdbuttons'){margin:0;padding:0}body{font:13.34px helvetica,arial,freesans,clean,sans-serif;-webkit-font-smoothing:subpixel-antialiased;line-height:1.4;padding:3px;background:#fff;border-radius:3px;-moz-border-radius:3px;-webkit-border-radius:3px}p{margin:1em 0}a{color:#4183c4;text-decoration:none}body{background-color:#fff;padding:30px;margin:15px;font-size:14px;line-height:1.6}body>*:first-child{margin-top:0!important}body>*:last-child{margin-bottom:0!important}@media screen{body{box-shadow:0 0 0 1px #cacaca,0 0 0 4px #eee}}h1,h2,h3,h4,h5,h6{margin:20px 0 10px;padding:0;font-weight:bold;-webkit-font-smoothing:subpixel-antialiased;cursor:text}h1{font-size:28px;color:#000}h2{font-size:24px;border-bottom:1px solid #ccc;color:#000}h3{font-size:18px;color:#333}h4{font-size:16px;color:#333}h5{font-size:14px;color:#333}h6{color:#777;font-size:14px}p,blockquote,table,pre{margin:15px 0}ul{padding-left:30px}ol{padding-left:30px}ol li ul:first-of-type{margin-top:0}hr{background:transparent url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAYAAAAECAYAAACtBE5DAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBNYWNpbnRvc2giIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6OENDRjNBN0E2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6OENDRjNBN0I2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo4Q0NGM0E3ODY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo4Q0NGM0E3OTY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PqqezsUAAAAfSURBVHjaYmRABcYwBiM2QSA4y4hNEKYDQxAEAAIMAHNGAzhkPOlYAAAAAElFTkSuQmCC) repeat-x 0 0;border:0 none;color:#ccc;height:4px;padding:0}body>h2:first-child{margin-top:0;padding-top:0}body>h1:first-child{margin-top:0;padding-top:0}body>h1:first-child+h2{margin-top:0;padding-top:0}body>h3:first-child,body>h4:first-child,body>h5:first-child,body>h6:first-child{margin-top:0;padding-top:0}a:first-child h1,a:first-child h2,a:first-child h3,a:first-child h4,a:first-child h5,a:first-child h6{margin-top:0;padding-top:0}h1+p,h2+p,h3+p,h4+p,h5+p,h6+p,ul li>:first-child,ol li>:first-child{margin-top:0}dl{padding:0}dl dt{font-size:14px;font-weight:bold;font-style:italic;padding:0;margin:15px 0 5px}dl dt:first-child{padding:0}dl dt>:first-child{margin-top:0}dl dt>:last-child{margin-bottom:0}dl dd{margin:0 0 15px;padding:0 15px}dl dd>:first-child{margin-top:0}dl dd>:last-child{margin-bottom:0}blockquote{border-left:4px solid #DDD;padding:0 15px;color:#777}blockquote>:first-child{margin-top:0}blockquote>:last-child{margin-bottom:0}table{border-collapse:collapse;border-spacing:0;font-size:100%;font:inherit}table th{font-weight:bold;border:1px solid #ccc;padding:6px 13px}table td{border:1px solid #ccc;padding:6px 13px}table tr{border-top:1px solid #ccc;background-color:#fff}table tr:nth-child(2n){background-color:#f8f8f8}img{max-width:100%}code,tt{margin:0 2px;padding:0 5px;white-space:nowrap;border:1px solid #eaeaea;background-color:#f8f8f8;border-radius:3px;font-family:Consolas,'Liberation Mono',Courier,monospace;font-size:12px;color:#333}pre>code{margin:0;padding:0;white-space:pre;border:0;background:transparent}.highlight pre{background-color:#f8f8f8;border:1px solid #ccc;font-size:13px;line-height:19px;overflow:auto;padding:6px 10px;border-radius:3px}pre{background-color:#f8f8f8;border:1px solid #ccc;font-size:13px;line-height:19px;overflow:auto;padding:6px 10px;border-radius:3px}pre code,pre tt{background-color:transparent;border:0}.poetry pre{font-family:Georgia,Garamond,serif!important;font-style:italic;font-size:110%!important;line-height:1.6em;display:block;margin-left:1em}.poetry pre code{font-family:Georgia,Garamond,serif!important;word-break:break-all;word-break:break-word;-webkit-hyphens:auto;-moz-hyphens:auto;hyphens:auto;white-space:pre-wrap}sup,sub,a.footnote{font-size:1.4ex;height:0;line-height:1;vertical-align:super;position:relative}sub{vertical-align:sub;top:-1px}@media print{body{background:#fff}img,pre,blockquote,table,figure{page-break-inside:avoid}body{background:#fff;border:0}code{background-color:#fff;color:#333!important;padding:0 .2em;border:1px solid #dedede}pre{background:#fff}pre code{background-color:white!important;overflow:visible}}@media screen{body.inverted{color:#eee!important;border-color:#555;box-shadow:none}.inverted body,.inverted hr .inverted p,.inverted td,.inverted li,.inverted h1,.inverted h2,.inverted h3,.inverted h4,.inverted h5,.inverted h6,.inverted th,.inverted .math,.inverted caption,.inverted dd,.inverted dt,.inverted blockquote{color:#eee!important;border-color:#555;box-shadow:none}.inverted td,.inverted th{background:#333}.inverted h2{border-color:#555}.inverted hr{border-color:#777;border-width:1px!important}::selection{background:rgba(157,193,200,0.5)}h1::selection{background-color:rgba(45,156,208,0.3)}h2::selection{background-color:rgba(90,182,224,0.3)}h3::selection,h4::selection,h5::selection,h6::selection,li::selection,ol::selection{background-color:rgba(133,201,232,0.3)}code::selection{background-color:rgba(0,0,0,0.7);color:#eee}code span::selection{background-color:rgba(0,0,0,0.7)!important;color:#eee!important}a::selection{background-color:rgba(255,230,102,0.2)}.inverted a::selection{background-color:rgba(255,230,102,0.6)}td::selection,th::selection,caption::selection{background-color:rgba(180,237,95,0.5)}.inverted{background:#0b2531;background:#252a2a}.inverted body{background:#252a2a}.inverted a{color:#acd1d5}}.highlight .c{color:#998;font-style:italic}.highlight .err{color:#a61717;background-color:#e3d2d2}.highlight .k,.highlight .o{font-weight:bold}.highlight .cm{color:#998;font-style:italic}.highlight .cp{color:#999;font-weight:bold}.highlight .c1{color:#998;font-style:italic}.highlight .cs{color:#999;font-weight:bold;font-style:italic}.highlight .gd{color:#000;background-color:#fdd}.highlight .gd .x{color:#000;background-color:#faa}.highlight .ge{font-style:italic}.highlight .gr{color:#a00}.highlight .gh{color:#999}.highlight .gi{color:#000;background-color:#dfd}.highlight .gi .x{color:#000;background-color:#afa}.highlight .go{color:#888}.highlight .gp{color:#555}.highlight .gs{font-weight:bold}.highlight .gu{color:#800080;font-weight:bold}.highlight .gt{color:#a00}.highlight .kc,.highlight .kd,.highlight .kn,.highlight .kp,.highlight .kr{font-weight:bold}.highlight .kt{color:#458;font-weight:bold}.highlight .m{color:#099}.highlight .s{color:#d14}.highlight .na{color:#008080}.highlight .nb{color:#0086b3}.highlight .nc{color:#458;font-weight:bold}.highlight .no{color:#008080}.highlight .ni{color:#800080}.highlight .ne,.highlight .nf{color:#900;font-weight:bold}.highlight .nn{color:#555}.highlight .nt{color:#000080}.highlight .nv{color:#008080}.highlight .ow{font-weight:bold}.highlight .w{color:#bbb}.highlight .mf,.highlight .mh,.highlight .mi,.highlight .mo{color:#099}.highlight .sb,.highlight .sc,.highlight .sd,.highlight .s2,.highlight .se,.highlight .sh,.highlight .si,.highlight .sx{color:#d14}.highlight .sr{color:#009926}.highlight .s1{color:#d14}.highlight .ss{color:#990073}.highlight .bp{color:#999}.highlight .vc,.highlight .vg,.highlight .vi{color:#008080}.highlight .il{color:#099}.highlight .gc{color:#999;background-color:#eaf2f5}.type-csharp .highlight .k,.type-csharp .highlight .kt{color:#00F}.type-csharp .highlight .nf{color:#000;font-weight:normal}.type-csharp .highlight .nc{color:#2b91af}.type-csharp .highlight .nn{color:#000}.type-csharp .highlight .s,.type-csharp .highlight .sc{color:#a31515}