From a4c21542838d9e6f41e91d12e65299b042124c5c Mon Sep 17 00:00:00 2001 From: David Klein Date: Wed, 24 Jun 2020 13:36:51 +0200 Subject: [PATCH 1/3] Replaced reference to bibliography.bib with DOI link --- .zenodo.json | 2 +- DESCRIPTION | 4 ++-- README.md | 6 +++--- vignettes/goxygen.Rmd | 6 ++---- 4 files changed, 8 insertions(+), 10 deletions(-) diff --git a/.zenodo.json b/.zenodo.json index a5b9e66..0b7817c 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,6 +1,6 @@ { "title": "goxygen: In-Code documentation for GAMS", - "version": "0.39.2", + "version": "0.39.3", "description": "

A collection of tools which extract a model documentation from GAMS code and comments. In order to use the package you need to install pandoc and pandoc-citeproc first (https://pandoc.org/).<\/p>", "creators": [ { diff --git a/DESCRIPTION b/DESCRIPTION index 112c4f1..edbbe33 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: goxygen Type: Package Title: In-Code documentation for GAMS -Version: 0.39.2 +Version: 0.39.3 Date: 2020-06-24 Authors@R: c(person("Jan Philipp", "Dietrich", email = "dietrich@pik-potsdam.de", role = c("aut","cre")), person("Kristine", "Karstens", email = "karstens@pik-potsdam.de", role = "aut")) @@ -17,4 +17,4 @@ Suggests: testthat, knitr, rmarkdown VignetteBuilder: knitr -ValidationKey: 7227304 +ValidationKey: 7245741 diff --git a/README.md b/README.md index d3a5911..770be15 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # In-Code documentation for GAMS -R package **goxygen**, version **0.39.2** +R package **goxygen**, version **0.39.3** [![Travis build status](https://travis-ci.com/pik-piam/goxygen.svg?branch=master)](https://travis-ci.com/pik-piam/goxygen) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1411404.svg)](https://doi.org/10.5281/zenodo.1411404) [![codecov](https://codecov.io/gh/pik-piam/goxygen/branch/master/graph/badge.svg)](https://codecov.io/gh/pik-piam/goxygen) @@ -47,7 +47,7 @@ In case of questions / problems please contact Jan Philipp Dietrich . +https://doi.org/10.5281/zenodo.1411404), R package version 0.39.3, . A BibTeX entry for LaTeX users is @@ -56,7 +56,7 @@ A BibTeX entry for LaTeX users is title = {goxygen: In-Code documentation for GAMS}, author = {Jan Philipp Dietrich and Kristine Karstens}, year = {2020}, - note = {R package version 0.39.2}, + note = {R package version 0.39.3}, doi = {10.5281/zenodo.1411404}, url = {https://github.com/pik-piam/goxygen}, } diff --git a/vignettes/goxygen.Rmd b/vignettes/goxygen.Rmd index d15119b..a3854a8 100644 --- a/vignettes/goxygen.Rmd +++ b/vignettes/goxygen.Rmd @@ -22,7 +22,7 @@ Goxygen provides tools to extract a model documentation from GAMS code, includin In order to use the package you need to install pandoc and pandoc-citeproc first (https://pandoc.org/). -Goxygen can extract the documentation from plain GAMS code (see next section) or from GAMS models that have a modularized structure as described in dietrich_magpie4 (see further down). +Goxygen can extract the documentation from plain GAMS code (see next section) or from GAMS models that have a modularized structure as described in http://dx.doi.org/10.5194/gmd-12-1299-2019 (see further down). ## Running goxygen on plain GAMS code @@ -85,7 +85,7 @@ The short example GAMS file contains all identifiers available in goxygen. The r ## 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_magpie4. 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 artificial and achieved only by 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. +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 in http://dx.doi.org/10.5194/gmd-12-1299-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 artificial and achieved only by 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: @@ -103,5 +103,3 @@ goxygen(path = "tmp-modular/dummymodel", output = "html", cff = "HOWTOCITE.cff") ``` Please find the goxygen output in the folder `tmp-modular/dummymodel/doc`. - -## References From 45d12bbd8c08345ec7a7eb1d7c8dc478ab91bad9 Mon Sep 17 00:00:00 2001 From: David Klein Date: Thu, 25 Jun 2020 15:59:59 +0200 Subject: [PATCH 2/3] Fix paths in copy command --- .zenodo.json | 2 +- DESCRIPTION | 4 ++-- README.md | 8 ++++---- vignettes/goxygen.Rmd | 18 +++++++----------- 4 files changed, 14 insertions(+), 18 deletions(-) diff --git a/.zenodo.json b/.zenodo.json index 1f0a013..8db8911 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,6 +1,6 @@ { "title": "goxygen: In-Code documentation for GAMS", - "version": "0.39.4", + "version": "0.39.5", "description": "

A collection of tools which extract a model documentation from GAMS code and comments. In order to use the package you need to install pandoc and pandoc-citeproc first (https://pandoc.org/).<\/p>", "creators": [ { diff --git a/DESCRIPTION b/DESCRIPTION index 4a8c7e5..b6ccdef 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: goxygen Type: Package Title: In-Code documentation for GAMS -Version: 0.39.4 +Version: 0.39.5 Date: 2020-06-25 Authors@R: c(person("Jan Philipp", "Dietrich", email = "dietrich@pik-potsdam.de", role = c("aut","cre")), person("Kristine", "Karstens", email = "karstens@pik-potsdam.de", role = "aut")) @@ -17,4 +17,4 @@ Suggests: testthat, knitr, rmarkdown VignetteBuilder: knitr -ValidationKey: 7264572 +ValidationKey: 7283010 diff --git a/README.md b/README.md index 2bc4bd5..5ea49ba 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # In-Code documentation for GAMS -R package **goxygen**, version **0.39.4** +R package **goxygen**, version **0.39.5** [![Travis build status](https://travis-ci.com/pik-piam/goxygen.svg?branch=master)](https://travis-ci.com/pik-piam/goxygen) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1411404.svg)](https://doi.org/10.5281/zenodo.1411404) [![codecov](https://codecov.io/gh/pik-piam/goxygen/branch/master/graph/badge.svg)](https://codecov.io/gh/pik-piam/goxygen) @@ -46,8 +46,8 @@ In case of questions / problems please contact Jan Philipp Dietrich . +Dietrich J, Karstens K (2020). _goxygen: In-Code documentation for GAMS_. doi: 10.5281/zenodo.1411404 (URL: https://doi.org/10.5281/zenodo.1411404), R +package version 0.39.5, . A BibTeX entry for LaTeX users is @@ -56,7 +56,7 @@ A BibTeX entry for LaTeX users is title = {goxygen: In-Code documentation for GAMS}, author = {Jan Philipp Dietrich and Kristine Karstens}, year = {2020}, - note = {R package version 0.39.4}, + note = {R package version 0.39.5}, doi = {10.5281/zenodo.1411404}, url = {https://github.com/pik-piam/goxygen}, } diff --git a/vignettes/goxygen.Rmd b/vignettes/goxygen.Rmd index 2213ef3..ebc4d27 100644 --- a/vignettes/goxygen.Rmd +++ b/vignettes/goxygen.Rmd @@ -27,23 +27,21 @@ Goxygen can extract the documentation from plain GAMS code (see next section) or ## Running goxygen on plain GAMS code -We take the GAMS code example from this package and save it to `tmp-plain.gms`: +We take the GAMS code example from this package and save it to `dummymodel-plain`: ```{r eval=FALSE} -# create temporary folder for the plain GAMS model -dir.create("tmp-plain") # copy the folder containing a simple dummy model with goxygen comments -file.copy(from = system.file("dummymodel-plain",package="goxygen"), to = "tmp-plain", recursive = TRUE) +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 format. If you want the documentation in pdf format simply set `output = "pdf"`. ```{r eval=FALSE} library(goxygen) -goxygen(path = "tmp-plain", mainfile = "0_main.gms", output = "html", cff = "HOWTOCITE.cff") +goxygen(path = "dummymodel-plain/", mainfile = "0_main.gms", output = "html", 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 `tmp-plain/doc`. +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 @@ -91,16 +89,14 @@ This was a simple example of a GAMS model in a single file with a plain structur 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: ```{r eval=FALSE} -# create a temporary folder for the modularized GAMS model -dir.create("tmp-modular") # copy all files and folders containing the modular dummy model -file.copy(from = system.file("dummymodel",package="gms"), to = "tmp-modular", recursive = TRUE) +file.copy(from = system.file("dummymodel",package="gms"), to = ".", recursive = TRUE) ``` Now execute `goxygen` on the modular GAMS model: ```{r eval=FALSE} -goxygen(path = "tmp-modular/dummymodel", output = "html", cff = "HOWTOCITE.cff") +goxygen(path = "dummymodel/", output = "html", cff = "HOWTOCITE.cff") ``` -Please find the goxygen output in the folder `tmp-modular/dummymodel/doc`. +Please find the goxygen output in the folder `dummymodel/doc`. From 2cd9e048f776000cdc543f34e6942754e638d1f0 Mon Sep 17 00:00:00 2001 From: David Klein Date: Thu, 25 Jun 2020 16:04:59 +0200 Subject: [PATCH 3/3] Add caption References --- vignettes/goxygen.Rmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/vignettes/goxygen.Rmd b/vignettes/goxygen.Rmd index ebc4d27..6c78aab 100644 --- a/vignettes/goxygen.Rmd +++ b/vignettes/goxygen.Rmd @@ -100,3 +100,5 @@ goxygen(path = "dummymodel/", output = "html", cff = "HOWTOCITE.cff") ``` Please find the goxygen output in the folder `dummymodel/doc`. + +## References