diff --git a/.zenodo.json b/.zenodo.json index 8db8911..97d3cf9 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,6 +1,6 @@ { "title": "goxygen: In-Code documentation for GAMS", - "version": "0.39.5", + "version": "0.39.6", "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 b6ccdef..5fba8be 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Package: goxygen Type: Package Title: In-Code documentation for GAMS -Version: 0.39.5 -Date: 2020-06-25 +Version: 0.39.6 +Date: 2020-06-26 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")) 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/). @@ -17,4 +17,4 @@ Suggests: testthat, knitr, rmarkdown VignetteBuilder: knitr -ValidationKey: 7283010 +ValidationKey: 7301844 diff --git a/README.md b/README.md index 5ea49ba..c3cf84e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # In-Code documentation for GAMS -R package **goxygen**, version **0.39.5** +R package **goxygen**, version **0.39.6** [![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) @@ -35,7 +35,7 @@ update.packages() The package comes with a vignette describing the basic functionality of the package and how to use it. You can load it with the following command (the package needs to be installed): ```r -vignette(goxygen) # Writing in-source documentation for GAMS code with goxygen +vignette(goxygen) # Creating GAMS model documentations with goxygen ``` ## Questions / Problems @@ -46,8 +46,9 @@ 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.6, . A BibTeX entry for LaTeX users is @@ -56,7 +57,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.5}, + note = {R package version 0.39.6}, doi = {10.5281/zenodo.1411404}, url = {https://github.com/pik-piam/goxygen}, } diff --git a/inst/dummymodel-plain/1_equations.gms b/inst/dummymodel-plain/equations.gms similarity index 90% rename from inst/dummymodel-plain/1_equations.gms rename to inst/dummymodel-plain/equations.gms index 5748601..a7afea2 100644 --- a/inst/dummymodel-plain/1_equations.gms +++ b/inst/dummymodel-plain/equations.gms @@ -30,3 +30,5 @@ equations *' ## Extra heading *' Here we create an extra heading not using goxygen syntax but using Markdown syntax. +*' +*' And you can also link back to the [index] page if you like. diff --git a/inst/dummymodel-plain/0_main.gms b/inst/dummymodel-plain/main.gms similarity index 84% rename from inst/dummymodel-plain/0_main.gms rename to inst/dummymodel-plain/main.gms index 5ce2159..8c9adc5 100644 --- a/inst/dummymodel-plain/0_main.gms +++ b/inst/dummymodel-plain/main.gms @@ -8,7 +8,7 @@ *' *' @limitations It is not really working as it is just an example. -$include "./1_equations.gms" +$include "./equations.gms" *' @stop The following code will be ignored by goxygen until the next identifier. @@ -20,4 +20,5 @@ display v01_intern.l; display vm_exchange.l; +*' You can also link other gms files, e.g. the equation file of this model [equations] diff --git a/tests/testthat/test-goxygen.R b/tests/testthat/test-goxygen.R index b36b779..ab3760d 100644 --- a/tests/testthat/test-goxygen.R +++ b/tests/testthat/test-goxygen.R @@ -15,6 +15,20 @@ test_that("extract documentation from modular dummy model", { expect_true(file.exists(paste0(docfolder,"/documentation.tex"))) }) +test_that("extract HTML documentation from modular dummy model with classic style", { + docfolder <- paste0(tempdir(),"/doc_modular_classic") + out <- try(goxygen(path = system.file("dummymodel",package="gms"), + htmlStyle = "classic", output="html", + docfolder = docfolder, includeCore = TRUE, cff = "HOWTOCITE.cff")) + expect_null(out) + expect_true(file.exists(paste0(docfolder,"/html/index.htm"))) + expect_true(file.exists(paste0(docfolder,"/html/core.htm"))) + expect_true(file.exists(paste0(docfolder,"/html/01_fancymodule.htm"))) + expect_true(file.exists(paste0(docfolder,"/html/02_crazymodule.htm"))) +}) + + + test_that("cache and unknown output", { docfolder <- paste0(tempdir(),"/doc_modular") expect_warning(out <- try(goxygen(path = system.file("dummymodel",package="gms"), diff --git a/vignettes/goxygen.R b/vignettes/goxygen.R new file mode 100644 index 0000000..5b14934 --- /dev/null +++ b/vignettes/goxygen.R @@ -0,0 +1,20 @@ +## ----setup, include = FALSE-------------------------------------------------------------- +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) + +## ----eval=FALSE-------------------------------------------------------------------------- +# # copy the folder containing a simple dummy model with goxygen comments +# file.copy(from = system.file("dummymodel-plain",package="goxygen"), to = ".", recursive = TRUE) + +## ----eval=FALSE-------------------------------------------------------------------------- +# goxygen::goxygen(path = "dummymodel-plain/", cff = "HOWTOCITE.cff") + +## ----eval=FALSE-------------------------------------------------------------------------- +# # copy all files and folders containing the modular dummy model +# file.copy(from = system.file("dummymodel",package="gms"), to = ".", recursive = TRUE) + +## ----eval=FALSE-------------------------------------------------------------------------- +# goxygen::goxygen(path = "dummymodel/", cff = "HOWTOCITE.cff") + diff --git a/vignettes/goxygen.Rmd b/vignettes/goxygen.Rmd index 6c78aab..b4f99cf 100644 --- a/vignettes/goxygen.Rmd +++ b/vignettes/goxygen.Rmd @@ -1,11 +1,12 @@ --- -title: "Writing in-source documentation for GAMS code with goxygen" +title: "Creating GAMS model documentations with goxygen" author: "David Klein, Jan Philipp Dietrich" -date: "17.06.2020" +date: "26.06.2020" bibliography: bibliography.bib +link-citations: true output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{goxygen} + %\VignetteIndexEntry{Creating GAMS model documentations with goxygen} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -19,13 +20,13 @@ knitr::opts_chunk$set( ## 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 this vignette we will focus on the HTML output. +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/). +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 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 [plain example](#plain)) or from GAMS models that have a modularized structure as described in @dietrich_magpie4 (see [modular example](#modular)). -## Running goxygen on plain GAMS code +## Running goxygen on plain GAMS code {#plain} We take the GAMS code example from this package and save it to `dummymodel-plain`: @@ -34,14 +35,13 @@ We take the GAMS code example from this package and save it to `dummymodel-plain 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"`. +and execute `goxygen` on this GAMS file to produce the documentation in HTML as well as PDF format. ```{r eval=FALSE} -library(goxygen) -goxygen(path = "dummymodel-plain/", mainfile = "0_main.gms", output = "html", cff = "HOWTOCITE.cff") +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 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 @@ -70,21 +70,21 @@ The short example GAMS file contains all identifiers available in goxygen. The r ## 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. +* **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 inclued in the documentation. +* **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 `@` in your goxygen comments."\" stands for the name of the corresponding bibtex entry. +* **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 `@` in your goxygen comments.`` 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. If you use a different filename than `CITATION.cff` please provide the name `cff = MYCITATION.cff`. +* **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:** This applies to the modular model structure only (see below). To link a module in the text use square brackets and the name of the module, e.g. `\[007_bond\]` +* **Internal links:** If you have [modular code](#modular) 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](#plain) 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 +## Running goxygen on modularized GAMS code {#modular} -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 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 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: @@ -96,9 +96,9 @@ file.copy(from = system.file("dummymodel",package="gms"), to = ".", recursive = Now execute `goxygen` on the modular GAMS model: ```{r eval=FALSE} -goxygen(path = "dummymodel/", output = "html", cff = "HOWTOCITE.cff") +goxygen::goxygen(path = "dummymodel/", cff = "HOWTOCITE.cff") ``` Please find the goxygen output in the folder `dummymodel/doc`. -## References +## References (#references)