goxygen {goxygen}

goxygen

Description

Documentation function which extracts a full model documentation from a modularized gams model. The function extracts comments used as documentation, extracts code and can extract and convert GAMS equations as latex code. Output is returned in Markdown, HTML and PDF format.

Usage

goxygen(
  path = ".",
  docfolder = "doc",
  cache = FALSE,
  output = c("html", "tex", "pdf"),
  htmlStyle = "ming",
  cff = "CITATION.cff",
  modularCode = is.modularGAMS(),
  unitPattern = c("\\(", "\\)"),
  includeCore = FALSE,
  mainfile = "main.gms",
  ...
)

Arguments

path

path to the model to be documented

docfolder

folder the documentation should be written to relative to model folder

cache

Boolean to allow read data from existing cache file

output

List of output to be written, available are "html","pdf" and "tex"

htmlStyle

visualization style to be used for the HTML creation. Currently available styles are "classic" and "ming". Ignored for outputs other than HTML.

cff

path to a citation file in citation-file-format (ignored if not existing)

modularCode

Boolean deciding whether code should be interpreted as modular GAMS code (only av)

unitPattern

pattern that is usedto identify the unit in the description, default =c("\(","\)")

includeCore

boolean whether core should be included or not, default=FALSE

mainfile

main file of the model

...

optional arguments to interfaceplot, passed via modules_interfaceplot.

Note

Documentation lines in the code must start with *' to be detected as documentation. Identifier at the beginning of each block describe what kind of documentation is given. All identifiers start with @ followed by the name of the identifier. Currently, following identifiers are available

• @title Title

• @authors List of authors

• @description Model description (only the documentation text will be interpreted)

• @equations Equation description (documentation text will be extracted and gams equations will be converted to latex code)

• @code Code description (documentation text and code will be extracted)

• @limitations details about limitations of an implementation

• @stop everything following will be ignored until the next identifier is mentioned again. Useful to stop a section

In addition you can store a model logo (100px height, 100px weight) as logo.png in the main folder of the model which then will be used in the HTML version of the documentation. If you want to add citations to your documentation you can do so by adding a bibtex file with the name literature.bib in the main folder of the model. To link these references in the text you can use the syntax @<id> in which "<id>" stands for the identifier given to the corresponding bibtex entry.

Author(s)

Jan Philipp Dietrich

See Also

codeCheck,interfaceplot

Examples

# make sure that pandoc is available
if(check_pandoc()) {
  # run goxygen for dummy model and store documentation as HTML in a temporary directory
  docfolder <- paste0(tempdir(),"/doc")
  goxygen(system.file("dummymodel",package="gms"),  docfolder=docfolder, output="html")
}