BioCro Development
Introduction
The documentation in this short book is aimed at developers—at those who will be writing new modules or modifying existing ones; and most especially at those fixing bugs in or adding new features to the BioCro simulation framework, and those involved with the overall maintenance of the BioCro package.
Note about the types of documentation in BioCro
There several categories of documentation for BioCro:
The top-level
README.mdis for general information about BioCro and is intended for potential users of the package.The files in the
mandirectory document the R functions and the data associated with the BioCro package. This documentation is intended for users of the package.The files in the
vignettesdirectory generally contain long-form documentation, also intended for users of the package.There is documentation generated by doxygen from comments in the C++ source files. General users will be interested in the documentation of the BioCro module library modules. Developers will be interested in the implementation of the dynamical systems simulator.
Finally, there are various
.mdand.Rmdfiles scattered throughout the package; these comprise the content of the Developer’s Manual (this manual, if you are reading this page as part of the bookdown book). This documentation is targeted at BioCro developers and maintainers.
The online documentation
All of the documentation mentioned above is available online at https://biocro.github.io.
When online documentation is generated
Documentation is automatically generated and published when a new release is created on GitHub. It is also generated (but not published) when a pull request is created or updated. In the latter case, the documentation is packaged as a Zip file available for download. To download a generated Zip file, go to the page for the Automatically generate documentation workflow and find a workflow run corresponding to the pull request whose documentation you wish to view. Click on it, and then find the artifact to download near the bottom of the page.1
In addition, one can manually trigger a workflow build of the documentation for a specific branch. To do this, go to the page for the Generate Documentation workflow and click on the Run workflow button. Choose which branch you want to document and which types of documentation to generate and then click the Run workflow button inside the dropdown window. (See the introductory section about types of documentation for discussion of the various types of BioCro documentation, and the following section for a discussion of how this documentation is packaged.)
Once the manually-triggered workflow has finished running, click on the link for the workflow run and look for the artifact to download at the bottom of the page.
The layout of the online documentation
The layout of the online documentation is in the form of a pkgdown document. Each of the categories of documentation listed above corresponds to a portion of this document as follows:
The
README.mddocument appears on the pkgdown home page (BioCro in the menu bar).The
manpages appear under the menu item References. (Note that although the page heading on the Reference page says Function reference, documentation of the various data sets is included as well.)The vignettes appear under the menu item Articles.
The Doxygen documentation may be accessed from the menu bar item C++ Library. Note that there are various forms of this documentation of varying concision and comprehensiveness.
The developer documentation (this book!) may be accessed by using the menu bar item Developer’s Manual.
Note that the Developer’s Manual, the C++ documentation, and the PDF-style vignettes are not well integrated into pkgdown, and the user will have to click the browser back button to return to pkgdown proper to once again have access to the pkgdown menu items.
In addition to the documentation proper, the menu bar contains some other useful links:
The About page gives useful information about the documentation—namely, which branch and commit version it corresponds to and the commit and generation dates.
The Changelog shows the BioCro version history.
Finally, there is a search box at the right of the menu bar. Note that this will not search the portions of the documentation not integrated into pkgdown, that is, it will not search the Developer’s Manual, the C++ documentation, or the PDF-style vignettes. And the search box only functions when the pkgdown document is deployed on a server.
If there is more than one run for a given pull request, you will probably want the latest one. If the Zip file has expired, you may have to manually call the workflow to regenerate it.
Manually-triggered workflow runs may be found at https://github.com/biocro/biocro/actions/workflows/document.yml↩︎