Creating GAMS model documentations with goxygen

Purpose and Functionality

Goxygen provides tools to extract a model documentation from GAMS code, including comments, code, and even GAMS equations, the latter of which are converted into latex code. This allows having GAMS code and explanatory text side by side in the same gms files, which makes it easier to keep the comments up to date with the code. The goxygen output is returned in HTML, Markdown, and PDF format.

In order to use the package you need to install pandoc and pandoc-citeproc first (https://pandoc.org/), if it is not already available on your system.

Goxygen can extract the documentation from plain GAMS code (see plain example) or from GAMS models that have a modularized structure as described in Dietrich et al. (2019) (see modular example).

Before testing please switch to a folder in which the test models can be copied and the documentation can be extracted (e.g. a temporary directory).

setwd(tempdir())

Running goxygen on plain GAMS code

We take the GAMS code example from this package and save it to dummymodel-plain:

# copy the folder containing a simple dummy model with goxygen comments 
file.copy(from = system.file("dummymodel-plain",package="goxygen"), to = ".", recursive = TRUE)

and execute goxygen on this GAMS file to produce the documentation in HTML as well as PDF format.

goxygen::goxygen(path = "dummymodel-plain/", cff = "HOWTOCITE.cff")

goxygen now searches the code for all lines starting with the goxygen tag *', interpretes the goxygen identifiers, and compiles the documentation into the format specified (html, tex, pdf). Please find the goxygen output in the folder dummymodel-plain/doc.

Goxygen syntax

The short example GAMS file contains all identifiers available in goxygen. The resulting document starts with a table of contents.

• @title Adds the heading with the title to the documentation.

• @description Contains the text describing the model. Start a new paragraph by adding a blank line that starts with *'.

• @authors List the authors of the model here.

• @limitations Explain the limitation of the model.

• @code All following lines of the model code will be displayed in the documentation output as code blocks. Lines starting with *' will be displayed as regular text.

• @equations starts the equation section where goxygen converts GAMS equations into LaTeX code so that they are displayed nicely in the output.

• @stop Everything following will be ignored until the next identifier is mentioned again. In this case the following code is not included in the documentation output:

  *' Even goxygen comments are ignored.
  display v01_intern.l;

  until the @code tag resumes the documentation.

Further features

• Markdown syntax: Since goxygen translates the code comments into Markdown before creating the other output formats from it, it is possible to use Markdown syntax in your goxygen comments. The markdown output itself is also stored in the documentation folder in the subfolder markdown.

• Including images: For example, in 1_equations.gms we included an image using Markdown syntax.

• Logo: Any file in your model’s main folder named logo.png (or other image formats) will be included in the documentation as model logo.

• References: To add literature references to the documentation please save a bibtex file literature.bib in the main folder of the model and link the references using @<id> in your goxygen comments.<id> stands for the name of the corresponding bibtex entry.

• CITATION.cff: Add meta information to your model, such as authors, name of the model, license etc. by adding a CITATION.cff file to your model’s main folder. This helps others to cite your model correctly and goxygen includes this meta information in the documentation (e.g. it will extract the model title and list of model authors from that file). If you use a different filename than CITATION.cff please provide the name cff = MYCITATION.cff.

• Internal links: If you have modular code and want to link a module in the text use square brackets and the name of the module, e.g. \[007_bond\]. In case of plain code use the name of the gms file you want to link, e.g. \[equations\]. The only exception is the file specified as main file of the model, which will always be referred to as \[index\].

Running goxygen on modularized GAMS code

This was a simple example of a GAMS model in a single file with a plain structure. As soon as model and code get more complex it is helpful to structure the model in a modular way, for example as described by Dietrich et al. (2019). This modular structure emulates in GAMS what would be functions and environments in other programming languages, since GAMS does not offer this feature. The separation is achieved via structural separation of the code and naming conventions. A module comprises the code of a content area that can be clearly separated from other content areas topic-wise and interacts with other modules only via clearly defined interfaces. The modular structure is clearly visible in the code through the naming convention mentioned and through the folder and file structure.

Goxygen is tailored to extract the documentation from this modular structure and to compile it to a clearly arranged documentation. Goxygen identifies modules and their interfaces, generates a interface plots that depict the interactions between modules, and lists the inputs and outputs of modules. For each module goxygen creates a new chapter in the documentation. We will demonstrate this using the simple example model from the gms package:

# copy all files and folders containing the modular dummy model
file.copy(from = system.file("dummymodel",package="gms"), to = ".", recursive = TRUE)

Now execute goxygen on the modular GAMS model:

goxygen::goxygen(path = "dummymodel/", cff = "HOWTOCITE.cff")

Please find the goxygen output in the folder dummymodel/doc.