Creating GAMS model documentations with goxygen

David Klein, Jan Philipp Dietrich

26.06.2020

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.

Further features

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.

References

Dietrich, J. P., B. L. Bodirsky, F. Humpenöder, I. Weindl, M. Stevanović, K. Karstens, U. Kreidenweis, et al. 2019. “MAgPIE 4 – a Modular Open-Source Framework for Modeling Global Land Systems.” Geoscientific Model Development 12 (4): 1299–1317. https://doi.org/10.5194/gmd-12-1299-2019.