2 Generating Documentation

2.1 Online documentation

Before we discuss generating documentation, we reiterate that you rarely need to. That is because the documentation is automatically generated for you and made available online!

The public documentation page at https://biocro.github.io provides up-to-date documentation for the latest release of BioCro. (This documentation will provide links to documentation of older releases.)

2.2 When to generate documentation

For the most part, developers should only need to generate documentation when they wish to check how changes made to it will be rendered, and whether that rendering is more or less correct. Changes a developer might make to the documentation include:

Changes to Doxygen-style comments in the C++ source code files
Changes to R function and data documentation (the files in the man directory)
Changes to any of the Markdown (.md) or R Markdown (.Rmd) files included in the Bookdown book (this book). (A list of all files used in forming the Bookdown book is in the configuration file bookdown/_bookdown.yml.)
Changes to the vignettes

In most other cases, developers can simply consult the automatically-generated online version of the documentation.

2.3 Documenting the C/C++ code.

To generate documentation for the C/C++ code, we use Doxygen.

2.3.1 Use cases for generating the Doxygen documentation

As mentioned in Section 2.2, developers should rarely need to generate documentation themselves since all of the documentation is regularly generated and published on-line. But there are cases where it makes sense to “do it yourself.” For Doxygen, these include:

You are altering the code or documentation of a particular C++ source file, and you want to check that changes you make show up correctly in the generated documentation.
You want a local copy of the Doxygen documentation because you don’t want to rely upon always having an internet connection.
You are making large-scale changes to the code, and it would be useful to have a version of the documentation that tracks with your changes.
You prefer a different presentation style for the documentation than is used in the on-line version.

Use Cases 2 and 3 are best addressed using the simple methods of Section 2.3.4. Use Case 1 is greatly facilitated by speeding up Doxygen using the methods discussed in Section 2.3.5. Lastly, Use Case 4, which requires a more extensive knowledge of Doxygen, is discussed in Section 2.3.6.

If none of these use cases apply to you, you most likely can simply use the on-line documentation (follow the C++ Library menu-bar link) and skip the rest of this chapter.

2.3.2 Required software

Doxygen (version 1.9.2 or higher)
The Graph visualization toolkit (“GraphViz”; version 2.38 or higher)

You can get by without this if you don’t care about generating the dependency and inheritance graphs. If you don’t have GraphViz installed, set “HAVE_DOT = NO” in the customization file (see below).
A LaTeX distribution

This is needed only if you set USE_MATHJAX = NO, or if you want to generate the PDF version of the documentation.
Ghostscript

You may be able to get by without this. You will need it, however, if you wish to generate HTML documentation that doesn’t rely on MathJAX.⁵
Gnu Make (version 4.3 or higher)⁶

This is needed only if you want to take advantage of the Makefile recipes.

2.3.3 Installation

Binary distributions of Doxygen for Linux x86-64, for Windows (Vista and later), and for macOS (10.14 and later) are available on the Doxygen Downloads page. To compile Doxygen from source, see the Doxygen Installation page.

If you use a package manager, installation is quite easy. For example, running

sudo apt-get install doxygen graphviz ghostscript

on Ubuntu will get you not only Doxygen, but Ghostscript and the Graph visualization toolkit as well. (To do something similar on a Mac with Homebrew, run brew install doxygen graphviz ghostscript.)

Depending on your system setup and operating system, you may additionally need to take pains to ensure that all required tools—gs, make, dot (from Graphviz), and doxygen itself—are on your system path.

2.3.4 Generating the Documentation

If you have Make installed

By far the easiest way to generate the complete Doxygen documentation with more or less the same customizations as appear in the on-line version is to open a terminal to the doxygen directory and run

make all-html

(Since all-html is the default Make target, you can also simply type make.) This will generate the most complete HTML version of the Doxygen documentation.⁷ To view it, open your browser to the landing page for the documentation, located at doxygen/doxygen_docs_complete/html/index.html. (On many systems, typing

make view

will generate the documentation and open it in a browser in a single step.)

There are other Make targets available. To see a list, run

make help

These other Make targets may be useful if you want a PDF version of the documentation; or if you want to concentrate on the documentation of the BioCro modules only, or conversely, on only the C++ BioCro framework.

If you don’t have Make installed

Doxygen can be run directly by simply opening a terminal to the doxygen directory and typing

doxygen

on the command line. This produces almost the same results as running make. The differences are

The browser won’t automatically open the documentation, as it does when you run make view.
The About page won’t show information from Git about the state your working copy of the BioCro repository was in at the time you generated the documentation.
The location of the generated documentation’s landing page will be doxygen/html/index.html rather than doxygen/doxygen_docs_complete/html/index.html.
The canned Doxygen customization sets provided by Makefile are not available when you run doxygen directoy.

2.3.5 Speeding up Doxygen

Method 1

By far, the most time consuming part of generating the Doxygen documentation is creating the graphs showing relationships between program components. You can speed up Doxygen tremendously by disabling the generation of these graphs. This is particularly recommended if you are tweaking the documentation of some source code and want to quickly see how your changes affect the rendered documentation (see the first use case in Section 2.3.1).

To disable generation of graphs:

Create a file called Doxyfile in the directory doxygen/customizations.
Insert the single line HAVE_DOT = NO into this file.

(If doxygen/customizations/Doxyfile already exists, simply add the line HAVE_DOT = NO to it.)

Doing these two steps will override the setting HAVE_DOT = YES contained in doxygen/Doxyfile.

(Bash shell users can disable graph generation for a single call of doxygen by running the command

(cat Doxyfile; echo "HAVE_DOT = NO") | doxygen -

in the doxygen directory. If you use a different shell, see the question Can I configure doxygen from the command line? in the Doxygen FAQ.)

Once you are satisfied with the way your Doxygen comments are rendered, you can, if you like, generate the documentation with the graphs by removing the HAVE_DOT = NO line from doxygen/customizations/Doxyfile.⁸

Method 2

Another way to speed up Doxygen is to run it only on the particular file whose documentation you are tweaking. For example, if you are adding to or changing the documentation in the source file

src/module_library/partitioning_coefficient_logistic.h

you can simply run

(cat Doxyfile; echo "INPUT=../src/module_library/partitioning_coefficient_logistic.h") | doxygen -

in a Bash shell from the doxygen directory.⁹ This will run almost instantaneously!

(The down side is that you will only be able to view the documentation pertaining to that particular file. You won’t, for example, be able to click on links to parent classes or dependent files and see the related documentation of those program entities.)

2.3.6 Doxygen for power users: Customizing Doxygen builds

This section addresses Use Case 4 of Section 2.3.1.

As we saw in Section 2.3.5, we can customize Doxygen runs by adding settings to the file doxygen/customizations/Doxyfile. For example, adding HAVE_DOT = NO to this file will override the setting HAVE_DOT = YES contained in doxygen/Doxyfile.

Doxygen offers dozens of settings that allow one to customize the generated documentation according to one’s preferences. We will highlight just a few of these settings that may be of special interest. For a complete list, see the Configuration section of the Doxygen documentation.

INPUT

We saw this setting in Section 2.3.5, where we used it to override the default setting (which looks at all of the C++ source files) in order to concentrate on a particular file. This vastly reduced Doxygen’s running time.

Note that multiple files (or directories!) may be listed here: simply separate the names with a space. Alternatively, list each on a separate line, using INPUT += on all but the first line. For example,

INPUT  = ../src/module_library/partitioning_coefficient_logistic.h
INPUT += ../src/framework

will yield documentation of the partitioning_coefficient_logistic module plus documentation of all of the source files in the src/framework directory.

Note that the Make-file recipes ignore settings made to INPUT in the Doxyfiles. You will have to call doxygen directly for these settings to have any effect.

Note also that Doxygen does not automatically recurse into subdirectories. For example, to also document the contents of src/framework/utils, you would need to add a third line:

INPUT += ../src/framework/utils

GENERATE_TREEVIEW

The setting in doxygen/Doxyfile is YES. Since the Tree View index takes up screen width, setting this value to NO may facilitate easier browsing of source code.

As with INPUT, the Make-file recipes normally override any setting made to this variable in the Doxyfiles. For this variable however, the value may be overridden on the command line using a call to Make of the form

make generate_treeview=NO <make target>

(see the note below). Or, simply call doxygen directly as in the INPUT case.

HAVE_DOT

As we saw in the previous section, setting this to NO will vastly reduce compilation time. (You should also set this to NO if you don’t have a copy of GraphViz, the package that contains the dot tool!) Unlike with INPUT and GENERATE_TREEVIEW, Make does respect the value this is set to in the Doxyfiles.

For finer-grained control over which diagrams get generated, see the Doxygen documentation section Configuration options related to the dot tool.

The doxygen/customizations directory contains a sample customization file named Doxyfile_customization_sample containing some suggestions for customizing your own Doxygen builds. To use this as a template, copy it to a file named Doxyfile (in the same directory) and modify it as you see fit.

Note on customizing Make builds

Certain customization variables are off limits when building the documentation using Make. These include the following: GENERATE_HTML, GENERATE_TREEVIEW, GENERATE_LATEX, INPUT, OUTPUT_DIRECTORY, EXTRACT_PRIVATE, and HTML_COLORSTYLE_HUE.

If any of these tags are set in the customization file doxygen/customizations/Doxyfile, those settings will be ignored when using Make. This is because the Make file itself sets values for these variables, overriding any settings in the Doxyfiles.

Three of these variables, however, can be set on the command line when running Make. This is done as follows:

GENERATE_TREEVIEW

To override the value YES that is set in Makefile, add a variable setting to the make command:

make generate_treeview=NO <make target>

HTML_COLORSTYLE_HUE

To override the value 143 that is set in Makefile, add a variable setting to the make command. For example

make color=30 <make target>

For the meaning of the hue number, see the Wikipedia article on this subject.¹⁰

EXTRACT_PRIVATE

To override the value YES that is set in Makefile``, add a variable setting to themake` command:

make extract_private=NO <make target>

This will produce documentation that focuses on the public API for classes, omitting documentation of private class members.

2.4 Building package vignettes

2.4.1 Required software

Unless you only want to build vignettes written in Markdown (“.Rmd” files), you will need a TeX installation of some sort. Here are two options:

Visit the CTAN starter page and choose and install a TeX distribution designed for your platform.
Alternatively, if you mainly want a TeX installation for use in R, you can install the R tinytex package along with some extra needed LaTeX packages not included in TinyTeX by default by proceeding as follows:
```
install.packages('tinytex')
tinytex::install_tinytex()
# Install a few LaTeX packages needed by the vignettes but not
# included in tinytex:
tinytex::tlmgr_install(c('siunitx', 'babel-english',
                         'footnotebackref', 'listings',
                         'appendix', 'pgf'))
```
(If you install TeX in this way, you will either need to build the vignettes using one of the Alternative options given below or add TinyTex’s bin directory to your shell path. You can find the root of the TinyTex installation with the R function tinytex::tinytex_root().)

If you use the second alternative build option listed below, you will also need the R package devtools:
```
install.packages('devtools')
```

2.4.2 Build procedure

The following instructions assume that the root of the BioCro source tree is a directory named biocro.

Build the package by running R CMD build biocro from the command line in the directory containing biocro. This includes building the vignettes.
Then install using R CMD INSTALL BioCro_xxx.tar.gz, where xxx is the version number.
The vignettes should now be available as HTML or PDF files located in path_to_rlib/BioCro/doc, where path_to_rlib is the path to your R library directory. An easy way to pull up an index to the vignettes in a web browser is to run the command browseVignettes('BioCro') in an R session.

2.4.3 Alternative options

Here are some alternative methods of building vignettes that don’t require re-installing BioCro.

From an R session running in biocro/vignettes, type tools::buildVignette(XXX), where XXX is the name of the particular vignette you wish to build. (It should have extension .Rnw or .Rmd.) The resulting PDF or HTML file will appear in biocro/vignettes.

This method is relatively fast and so is especially useful if you are writing a new vignette or revising an existing one. If the vignette being built uses any BioCro code, there must be a version of BioCro installed.
From an R session running in any directory of the BioCro source tree, type devtools::build_vignettes(). (Alternatively, start R from anywhere and pass the path to BioCro source tree as the first (“pkg”) argument to build_vignettes().) This method will modify .Rbuildignore and .gitignore, which may be annoying. The resulting HTML and PDF files will appear in the doc directory, which will be created if it doesn’t already exist.

This method doesn’t require that BioCro be installed. But it builds and installs BioCro in a temporary location and then builds all the vignettes, and thus it can be somewhat time consuming. Moreover, by default it gives very little indication of build progress, and so it may be useful to override this default and set quiet = FALSE in the function argument list.

2.5 Compiling and viewing the bookdown book

Note: A copy of the bookdown BioCro developer’s manual is automatically generated on BioCro’s GitHub documentation site at https://biocro.github.io and may be viewed by clicking on the Developer’s Manual menu-bar link found there. What follows, therefore, will mostly be of interest to developers working on revising the documentation who want to check the results of their revisions.

To generate the bookdown BioCro developer’s manual, do as follows:

Install Pandoc, if it is not already on your system. See https://pandoc.org/installing.html for instructions. (Note to RStudio users: As mentioned in the R Markdown Cookbook (https://bookdown.org/yihui/rmarkdown-cookbook/install-pandoc.html), RStudio comes with its own copy of Pandoc, so you may be able to get by without installing it separately.)
Install the R bookdown package, if it hasn’t been installed already. These instructions are written for bookdown version 0.22 or greater but may work for other versions.
In the bookdown directory of your BioCro source tree, run
```
Rscript -e "bookdown::render_book()"
```
Note: If you wish to run render_book from other than the bookdown directory, you may pass a path argument:
```
Rscript -e "bookdown::render_book(<path>)
```
Here, <path> denotes the path from the current directory to the bookdown directory.

This only works in bookdown versions 0.22 and later! With earlier versions, you can make use of the xfun::in_dir function:
```
xfun::in_dir('<path>', bookdown::render_book())
```
Again, <path> here denotes the path from the current directory to the bookdown directory.

Note: Because some sections of the book are contained in their own files rather than being in a larger file comprising a complete chapter, render_book will issue a warning such as the following, which may be safely ignored:

"In split_chapters(output, gitbook_page, number_sections, split_by, :

You have 13 Rmd input file(s) but only 7 first-level heading(s). Did you forget first-level headings in certain Rmd files?"
In a Web browser, open bookdown/_book/index.html.

Ghostscript is used to convert the PostScript files that are generated for formulas in the documentation into bitmaps. But MathJax provides an alternative method of rendering formulas in the HTML documentation, and so Ghostscript is unneeded as long as the Doxygen configuration variable USE_MATHJAX is set to YES. This is the BioCro default setting.

If Ghostscript is used, there may be some compatibility issues between Ghostscript and Doxygen. If you encounter problems, see Doxygen issue #7290 and Doxygen issue #8107 for further information.

On the other hand, use of MathJax requires a working internet connection, at least until your browser downloads and caches the MathJax code file. And it requires that JavaScript be enabled.↩︎
Although versions earlier than 4.3 will probably mostly work, you will get a warning when you use them.↩︎
Some users will have to type gmake in place of make to get the latest version of Gnu Make. Type make --version or gmake --version to see exactly what version you are calling.↩︎
If you are compiling the documentation using Make and haven’t changed any source files since last running it, add the -B option to force recompilation.↩︎
Alternatively, if you will be working extensively with one particular file, you could temporarily add
```
INPUT=../src/module_library/partitioning_coefficient_logistic.h
```
to the customization file (doxygen/customizations/Doxyfile). Then you would simply run
```
doxygen
```
from the doxygen directory.

Note that even though the customization file is in the doxygen/customizations directory, the file paths listed in the INPUT value should be relative to the doxygen directory!↩︎
Other settings that affect the color of the documentation are HTML_COLORSTYLE, HTML_COLORSTYLE_SAT, and HTML_COLORSTYLE_GAMMA. The values for these options must be set in the customization file doxygen/customizations/Doxyfile if using Make; alternately, if calling doxygen directly, they may be set on the command line; for example
```
(cat Doxyfile; echo "HTML_COLORSTYLE_SAT=255") | doxygen -
```
See the Configuration section of the Doxygen documentation for information about these settings.↩︎