"Online documentation for BioCro" {target="_blank"}
https://github.com/biocro/biocro/actions/workflows/automatically-call-document.yml "Documentation workflow runs (automatic)" {target="_blank"}
https://github.com/biocro/biocro/actions/workflows/document.yml "Documentation workflow runs (manual)" {target="_blank"}
[pkgdown]: https://pkgdown.r-lib.org/index.html "The pkgdown web site" {target="_blank"}
[^latest_version]: 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
There several categories of documentation for BioCro:
The top-level README.md
is for general information about BioCro
and is intended for potential users of the package.
The files in the man
directory 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 vignettes
directory 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 .md
and .Rmd
files 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.
All of the documentation mentioned above is available online at https://biocro.github.io.
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.[^latest_version]
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 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.md
document appears on the pkgdown home page (BioCro
in the menu bar).
The man
pages 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.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.