Skip to content

Priority pathogens website

Jump to bottom
ruthmccabe edited this page May 8, 2024 · 1 revision

The priority-pathogens website is a bifurcation of the content in the epirview website. The live views of the publications published by the Pathogen Epidemiology Review Group (PERG) are hosted on the priority-pathogens website. The epireview website now only contains vignettes that display the functionality of the package, as is conventionally the case with R packages.

The goal of this approach is to separate the development of epireview from the live updates of the analyses produced in each publication. This separation should make clearer the dependencies between epireview and priority-pathogens. Moreover, this separation will clarify the requirements for future pathogen leads; namely, using and contributing to epireview while conducting their analysis, and creating an R markdown file from their analysis that can be rendered in the priority-pathogens website.

This page outlines the following:

  • The steps to be taken to add to the website
  • How the priority-pathogen website is deployed
  • The dependencies between this website and epireview
  • A to-do list of improvements
  • The outstanding issues
  • The risks associate with the current deployment

Steps to add to the website

Below are the steps to add a webpage on the priority-pathogens website.

1.Create a new branch for your GitHub (GH) Pages content. A suggested name is gh-pages-content-, where should be replaced with the pathogen you’re working on.

  1. Create your R-markdown file and save in it the vignettes folder. The R-markdown files have a few requirements which are listed below. An example of a file that meets these requirements can be found here.

    a. They should use the epireview package wherever possible. This includes both in terms of data and analysis/plotting functions.

    b. Before you load epireview, you must install the specific version of epireview you used. You can do this using the code below:

     i. To install a specific version: remotes::install_github("mrc-ide/epireview@v0.1.0")

 ii. To install the latest version: remotes::install_github("mrc-ide/epireview")

    c. Any priority-pathogen specific functions must be sourced from an R script in the repo.

    d. Any additional resources used (e.g. shape files) must be available in the priority-pathogens repo.

    e. As an optional sense-check, you can check that your R-markdown file compiles locally with pkgdown. The steps to do this are given below. Note that applying these steps will create a docs folder, please don’t commit this folder or its contents.

     i. Set your R working directory to the root of the priority-pathogens repo

 ii. If it’s your first time attempting to build the site locally, run pkgdown::init_site(). Note: Running this again shouldn’t cause an error, if you get an error similar to “*/docs is non-empty and not built by pkgdown” then your site was not initialised correctly.

 iii. Next, to compile the R-markdown files in the vignettes folder, run pkgdown::build_articles()

 iv. If you’ve made changes to the home page by either editing the README file or the _pkgdown.yml, you can render it by using: pkgdown::build_home().

  2. Update the DESCRIPTION file to include any additional packages that you use. Please maintain the alphabetical order to make it easier for others to update this list.

  3. Commit the R-markdown file, DESCRIPTION, and related resources to GH.

  4. Make a pull request (PR) from your branch to main. Once you make a PR there will be a check that your website compiles. If it compiles successfully, there will be a green tick. If it fails, there will be a red cross. If your workflow fails, you will need to fix the error. This maybe be a trial-and-error process (and can be frustrating since the action takes a while to complete). To see why the workflow failed you can look at the action workflow. Once you have a green tick you can ask someone to review your PR - please don’t ask for a review prior to this.

image

  1. If you would like to edit an existing page on the website, you will need to make a new branch. Once your changes are complete, make a PR from this branch to main. The same process in step 5 for checking that the website complies apply. As a reminder, you don’t need to commit all the files in step 4, you only need to commit the files you’ve changed.

In all cases the website should deploy automatically when a PR is merged into main. Additionally, there is a manual trigger which can be activated online from the workflow, which can be accessed from the GH Actions tab.

Priority Pathogen website deployment

The priority pathogens website is deployed on GH Pages using pkgdown. The deployment of the website is controlled by a GH Actions workflow. The action triggers when a commit is pushed to main (this includes merging a pull request, which will be the only way to push to main in this project). The action renders a website using pkgdown; the articles on the website can be found in the vignettes folder. Although the components of the website are generated in the main branch, the deploy action commits the generated components to the root of the gh-pages branch. The GH Pages website is built from the root of this branch.

The resources to generate and deploy the website are given below (paths relative to the root of the repo).

Website resources:

  • _pkgdown.yml
  • DESCRIPTION
  • README.md
  • vignettes/*.Rmds
  • man/figures/logo.png

Website deployment:

  • .github/workflows/render_website.yml

Note: The use of pkgdown is in this context is unconventional since the priority-pathogens code base is not a package, but there are a few reasons for this decision. Firstly, using pkgdown automatically renders the CSS and the bootstrap theme required to match the epireview website format. Secondly, the use of pkgdown simplifies the deployment process, particularly for future pathogen leads who will need to add their own webpages. The disadvantage of this approach is that there is less control over the website components and there are certain package components – such as the version number and the use of a DESCRIPTION file – that cannot be removed. Assuming the required expertise is available, future updates should consider moving away from pkgdown to a more conventional web development approach.

Dependencies between priority-pathogens website and epireview package

All website dependencies between the priority-pathogens website exist within the R markdown file. Currently there are two main dependencies:

  1. The markdown file uses data from epireview
  2. The markdown file uses functions from epireview. These functions will likely come from a tagged version of epireview.

As future dependencies occur, they should be documented here. These dependencies do not account for the dependencies between other analyses conducted in priority pathogens and epireview.

Todo

  1. Update README for consistency and link between priority-pathogens and epireview
  2. Consider website-specific triggers, e.g. only trigger if specific paths are pushed to. I’m not sure what the best CI/CD practice is here.
  3. Either tag epireview for Lassa publication or refactor Lassa markdown as changes are made to epireview
  4. Clean-up epireview a. Edit epireview article page b. Remove pathogen_marburg.Rmd from vignettes; first merge PR? c. Add reference to priority-pathogens
  5. Figure out process flow for testing the GH Action and compilation manually
  6. PR-template
  7. Tagging

Issues

  1. If we used tagged versions of epireview the data will be a snapshot of the version.
    Solutions: a. Read in raw csv (must be a public repo for url to be static – I think) i. Issue with data format changes b. Have the Rmds use the latest version of epireview; this will require continuous refactoring of the R markdown files.

  2. Cross-repo hook: for now, we can run manually. If we do use a cross-repo hook it’s from epireview to priority-pathogens. Risks (indicate if high or low risk):

  • Time dependency [low risk]: GH Actions default timeout is 360 minutes (6 hours), if jobs take longer to compile than this (unlikely), we’ll need to split-up the markdown compilation [1].
  • Dependency on pkgdown (2.0.7) [low risk]: A specific version (the latest available when building the site) is installed since if pkgdown functions change website the build might break. This should be reviewed when possible and updated so the latest version of pkgdown that works for our build is used.
Clone this wiki locally