The Generate Documentation workflow, contained in file
document.yml
, builds the BioCro User's Manual, the BioCro
Developer's Manual, and the Doxygen BioCro C++ Library documentation
and copies and commits the result to the repository given as the value
of the "PUBLISH_TO" environment variable (henceforth the
documentation repository; see the value contained in
document.yml
). That repository is in turn set up to publish to a
GitHub Pages Web site at the corresponding canonical location. (In
general, a repository named <organization>/<repository>
will be
published to the URL https://<organization>.github.io/<repository>
.)
The workflow runs
main
branch;(In the latter case, the documentation is not published but is made available as an artifact for download.) It may also be run manually on the GitHub site.
In order for this to all work correctly, a number of set-up steps were required. Here are the steps involved:
An SSH public/private key pair is generated on a work station using
the command ssh-keygen -t rsa -b 4096
. Use the -C
option to
include a comment; for example
ssh-keygen -t rsa -b 4096 \
-C "Let biocro/biocro deploy to biocro/BioCro-documentation"
You will be prompted for a file name for the key, and then for a pass-phrase. The pass-phrase should be empty.
This will generate a pair of files, one with the public key and
one with the private key. For example, if you choose biocro-key
as
the name of the file, this will be the name of the file containing the
private key, and the public key will be in a file called
biocro-key.pub
.
This key pair is needed in order to allow a workflow defined in the BioCro repository to push files to the documentation repository.
The private key must be added as an Actions secret in the BioCro
repository (this repository) under the name PRIVATE_SSH_KEY
. When
doing this, paste the entire contents of the private key file into
text area labeled Secret. (See
https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository.
The key name matches the reference secrets.PRIVATE_SSH_KEY
used in
the document.yml
workflow file.)
Create the documentation repository. Even though the Generate Documentation workflow will populate this repository, at least one file must be added to it to begin with in order for the workflow to run. (Suggestion: Add a README.md file when creating the repository; it can be blank.)
Add the public SSH key as a deploy key to the documentation repository under a suitable title; for example, "Access from biocro/biocro documentation workflow" (assuming "biocro/biocro" is the name of this repository). When doing this, paste the entire contents of the public key file into the text area labeled Key. (See https://docs.github.com/en/developers/overview/managing-deploy-keys#setup-2. The title "Access from biocro/biocro documentation workflow" is for informational purposes only and has no programmatic significance.)
Enable GitHub Pages for the documentation repository (see https://pages.github.com/). This results in the files in the documentation repository getting automatically published to the corresponding GitHub Pages web site.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.