Merge pull request #11 from phuse-org/tidy

copy edits

content/cicdworkflows-enhanced/_metadata.yaml

@@ -0,0 +1,4 @@
+comments:
+  giscus: 
+    repo: phuse-og/devops
+    category: General

content/cicdworkflows-enhanced/index.qmd

@@ -0,0 +1,15 @@
+---
+pagetitle: Enhanced CICD workflows
+title: Enhanced CICD workflows
+subtitle: CICD workflows for power users
+search: false
+listing:
+  contents: posts
+  sort: "date desc"
+  type: grid
+  categories: true
+  sort-ui: true
+  filter-ui: true
+  page-size: 12
+comments: false
+---

content/cicdworkflows-enhanced/posts/validate/validate.qmd

@@ -0,0 +1,59 @@
+---
+title: "theValidator"
+description: |
+  This workflow will take your documentation, and link it to unit testing, creating a report that links requirements (documentation) to tests of those requirements. 
+categories:
+  - Testing
+  - Documentation
+  - Validation
+date: 2023-08-01
+image: validate.jpg
+toc: true
+---
+
+:::{.callout-note style="margin-top: 0rem;" collapse="false"}
+## About the gh-action
+
+**Example of use:** [admiral R package](https://github.com/insightsengineering/thevalidatoR/blob/main/readme_files/report-0.1-admiral.pdf)
+
+**Expected output:** A PDF attached to a release.
+:::
+
+## Why should I use this?
+
+As a codebase grows, it becomes more likely you will end up with a number of links in your documentation. 
+These links can over time stop working - and often you won't know till a user flags your links or broken.
+
+This `gh-action` lets you stay on top of broken links, by actively scanning for them.
+
+## How do I set it up?
+
+Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch.
+
+
+```bash
+---
+name: Docs 📚
+
+on:
+  push:
+    branches:
+      - main
+      - devel
+  pull_request:
+    branches:
+      - main
+      - devel
+
+jobs:
+  links:
+    name: Links
+    uses: pharmaverse/admiralci/.github/workflows/links.yml@main
+    if: github.event_name == 'pull_request'
+```
+
+## The deets
+
+This gh-action uses lychee. If you need to prevent false positive deadlinks stopping the 
+process, you can use a `.lycheeignore` file. There is an example of this file [from 
+admiral here](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore).

content/cicdworkflows-minimum/_metadata.yaml

@@ -1,4 +1,4 @@
 comments:
   giscus: 
-    repo: realworlddatascience/realworlddatascience.github.io
+    repo: phuse-og/devops
     category: General

content/cicdworkflows-minimum/posts/code-coverage.qmd

@@ -26,7 +26,7 @@ coverage as a percentage of the *total number of lines covered by unit
 tests* vs. the *total number of lines in the codebase* in an R package.
 
 Using this github action gives you a badge that helps to show that the code is coverage. Calculating this 
-via CICD is useful as the amount of untested code can vary, e.g. a new feature is added but it is not tested. 
+via CICD is useful as the amount of untested code can vary, e.g. a new feature is added but it is not tested. People often use this metric as an indicator of code quality and maturity.
 
 It's important to note that code coverage is only telling you if a test exists, not that the test is 
 testing all that should be tested against that line of code. 

content/cicdworkflows-minimum/posts/pkgdown.qmd

@@ -20,9 +20,14 @@ toc: true
 
 ## Why should I use this?
 
-`pkgdown` is the most common framework for rendering R package documentation into a an HTML website. 
- Generating and uploading documentation manually makes it very easy for differences
-to be present 
+`pkgdown` is the most common framework for rendering R package documentation into a an HTML website. This `gh-action` will 
+generate the documentation, and deploy it to a gh-pages branch. It will also upload a copy of the documentation to the release. 
+
+This is important for multiple reasons:
+
+1. Because the documentation is generated automatically, you can make sure the documentation matches the code. Without CICD you are relying on users remembering to rebuild the documentation when they make changes.
+1. If you manually generate the documentation, you will need to store the built artefacts in your git repo. This will bloat your repo, and make it harder to work with.
+1. Because the documentation is versioned, you can always find the documentation that matches the version of the code you are using. This is important for reproducibility. 
 
 
 ## How do I set it up?

content/cicdworkflows-minimum/posts/r-cmd-check/r-cmd-check.qmd

@@ -30,7 +30,7 @@ If you have dependencies on other pharmaverse packages, it's likely you will als
 
 ## How do I set it up?
 
-Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch.
+Below is an example of using this `gh-action` whenever someone tries to make PR into your `main` or `devel` branch or updates the branch. We recomend you use this on both `main` and `devel` branches, as it will help you catch issues before they get into your main branch.
 
 
 ```bash

content/cicdworkflows-recommend/_metadata.yaml

@@ -1,4 +1,4 @@
 comments:
   giscus: 
-    repo: realworlddatascience/realworlddatascience.github.io
+    repo: phuse-og/devops
     category: General

content/cicdworkflows-recommend/posts/check-links/check-links.qmd

@@ -55,4 +55,4 @@ jobs:
 
 This gh-action uses lychee. If you need to prevent false positive deadlinks stopping the 
 process, you can use a `.lycheeignore` file. There is an example of this file [from 
-admiral here](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore).
+admiral here](https://github.com/pharmaverse/admiral/blob/devel/.lycheeignore).

index.qmd

@@ -31,6 +31,17 @@ listing:
     filter-ui: false
     max-items: 24
     feed: false
+  - id: cicdworkflows-enhanced
+    contents: 
+    - /content/cicdworkflows-enhanced
+    - "!index.qmd"
+    sort: "date desc"
+    type: grid
+    categories: true
+    sort-ui: false
+    filter-ui: false
+    max-items: 24
+    feed: false
 
 toc: false
 ---
@@ -65,14 +76,23 @@ the domain of devops, by data scientists, in late-stage drug development.
 ::: grid
 ::: {.g-col-12 .top-story-text}
 ## Getting started with CICD
+
+In this guidance, you'll see a number of `gh-actions` that you can use to implement CICD on your project. We have categorised these into three groups:
+
+- *Minimum CICD*: These are the minimum CICD tools we recommend for all packages on the pharmaverse. These CICD tools are focussed on ensuring your package works, and documentation matches the code.
+- *Recommended CICD*: These are tools we feel make your life developing and releasing robust code easier.
+- *Enhanced CICD*: These are tools are option tools for power users, or those with specific needs.
+
+Each CICD action is described via a common pattern, with an emphasis on why we recommend it, and how to use it.
+
 A recomended plan for success in implenting CICD on your project is to:
 
-- Read this post on the general anatomy of a `gh-action` [TODO]
+- [Read this post](post/posts/gh-actions.html) on the general anatomy of a `gh-action`
 - Browse our recomended `gh-action`'s below
 - Review this case study of CICD is used in `admiral`
 - Implement CICD on your git repo!
 
-We've also collected togther this list of external learning resources here: [TODO]
+We've also collected togther [this list of external learning resources](post/posts/external-resources.html).
 
 <!--# Notes on getting started 
 Provide a master version (e.g. here's a single file with all the recomended) [TODO]
@@ -125,5 +145,21 @@ releasing robust code easier.
 ::: {#cicdworkflows-recommend}
 :::
 
+:::
+:::
+
+::: {.content-container}
+::: {.listing-block}
+<a href="/content/cicdworkflows-enhanced/index.qmd">
+
+## Enhanced CICD
+
+The following CICD are tools are option tools for power users. 
+
+</a> 
+
+::: {#cicdworkflows-enhanced}
+:::
+
 :::
 :::

meetings/index.qmd

@@ -8,7 +8,7 @@ listing:
   - minutes
   - "!index.qmd"
   sort: "date desc"
-  type: table
+  type: default
 ---
 
 Meeting notes and minutes.

post/_metadata.yml

@@ -0,0 +1,3 @@
+title-block-banner: true
+sidebar: false
+page-layout: article

post/index.qmd

@@ -0,0 +1,12 @@
+---
+pagetitle: Posts | PharmaDevOps
+title: Posts
+subtitle: "Ad-hoc notes and posts"
+search: true
+listing:
+  contents:
+  - posts
+  - "!index.qmd"
+  sort: "date desc"
+  type: default
+---

post/posts/external-resources.qmd

@@ -0,0 +1,11 @@
+---
+pagetitle: refs
+title: External references
+subtitle: "A list of useful external references"
+date: 2023-10-23
+search: true
+---
+
+* [gh-action documention from GitHub](https://docs.github.com/en/actions)
+* [Tidyverse post on CICD for R devs](https://www.tidyverse.org/blog/2022/06/actions-2-0-0/)
+

post/posts/gh-actions.qmd

@@ -0,0 +1,42 @@
+---
+pagetitle: ghactions
+title: The anatomy of a gh-action
+subtitle: "Understanding what makes a github action tick"
+date: 2023-10-23
+search: true
+---
+
+GitHub Actions are a powerful automation and CI/CD (Continuous Integration/Continuous Deployment) platform provided by GitHub. It allows you to automate various tasks and workflows in response to events that occur in your GitHub repositories. Actions are defined using `YAML` files that specify the workflow to be executed. The workflow file typically has a `.yml` extension. Below is an explanation of the key syntax elements in a GitHub Actions workflow file as an annotated example:
+
+```yaml
+# Name: You can specify a name for your workflow. 
+# This is a human-readable description of the workflow 
+# and is not required for the workflow to function.
+name: My CI/CD Workflow
+
+# on: This specifies the events that trigger the workflow. 
+# You can set it to various events like pushes to a 
+# repository, pull requests, or even a schedule.
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+# jobs: This is the main section of the workflow file. 
+# It defines the jobs that are to be executed when 
+# the workflow is triggered.
+jobs:
+  build:
+    runs-on: ubuntu-latest # Specifies the type of virtual 
+    # machine or runner on which the job will run. GitHub 
+    # provides various runners for different platforms, 
+    # including Windows, Linux, and macOS.
+    steps: # Contains a list of steps that are executed 
+    # in the specified order. Steps are individual 
+    # tasks within a job.
+      - name: Checkout code
+        uses: actions/checkout@v2
+```