added navigation to HTML based documentation

pik-piam · Sep 7, 2018 · 22ed142 · 22ed142
1 parent 2b50bcd
commit 22ed142
Show file tree

Hide file tree

Showing 6 changed files with 154 additions and 10 deletions.
diff --git 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 = "[email protected]", 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
@@ -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
@@ -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('<div id="',id,'">','<ul>')
+    for(i in 1:length(names)) {
+      out <- c(out,paste0('<li><a href="',targets[i],'">',names[i],'</a></li>'))
+    }
+    out <- c(out,'</ul>','</div>')
+    return(out)
+  }
+
+  addMainHeaderHTML <- function(goxygen_conf) {
+    cfg <- readConf(goxygen_conf)
+
+    if(file.exists("images/logo.png")) {
+      logo <- '  <img id="logo" src="images/logo.png" height="100" alt="model logo" />'
+    } else {
+      logo <- NULL
+    }
+
+    if(!is.null(cfg$Version)) {
+      version <- paste0(" | Version ",cfg$Version)
+    } else {
+      version <- NULL
+    }
+
+    out <- c('<div id="mainheaderbox"></div>',
+             '<div id="mainheader">',
+             logo,
+             paste0('  <div id=mainheadertext><h1 id="mainheadertitle">Model Documentation</h1><h3 id="mainheaderversion">',version,'</h3></div>'),
+             paste0('  <small>created with <a href="https://github.com/pik-piam/goxygen">goxygen</a> ',packageVersion("goxygen"),'</small>'),
+             '</div>')
+    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=="<body>")
+      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
@@ -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
@@ -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))
+}
diff --git 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}