Initial commit

d-cameron · d-cameron · commit fb9413946973 · 2021-08-17T12:12:15.000+10:00
diff --git a/.Rbuildignore b/.Rbuildignore
@@ -0,0 +1,4 @@
+^LICENSE\.md$
+.github
+Dockerfile
+_pkgdown.yml
diff --git a/.github/workflows/basic_checks.yaml b/.github/workflows/basic_checks.yaml
@@ -0,0 +1,85 @@
+on: [push, pull_request]
+
+env:
+  cache-version: v1
+  repo-name: seandavi/buildabiocworkshop
+
+jobs:
+  job1:
+    runs-on: ubuntu-latest
+    container: bioconductor/bioconductor_docker:devel
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: Query dependencies and update old packages
+        run: |
+          BiocManager::install(ask=FALSE)
+          saveRDS(remotes::dev_package_deps(dependencies = TRUE), ".github/depends.Rds", version = 2)
+        shell: Rscript {0}
+        
+      - name: Cache R packages
+        if: runner.os != 'Windows'
+        uses: actions/cache@v1
+        with:
+          path: /usr/local/lib/R/site-library
+          key: ${{ env.cache-version }}-${{ runner.os }}-r-${{ hashFiles('.github/depends.Rds') }}
+          restore-keys: ${{ env.cache-version }}-${{ runner.os }}-r-
+
+      # This lets us augment with additional dependencies
+      - name: Install system dependencies
+        if: runner.os == 'Linux'
+        env:
+          RHUB_PLATFORM: linux-x86_64-ubuntu-gcc
+        run: |
+          Rscript -e "remotes::install_github('r-hub/sysreqs')"
+          sysreqs=$(Rscript -e "cat(sysreqs::sysreq_commands('DESCRIPTION'))")
+          sudo -s eval "$sysreqs"
+          
+      - name: Install dependencies
+        run: |
+          options(repos = c(CRAN = "https://cran.r-project.org"))
+          BiocManager::repositories()
+          remotes::install_deps(dependencies = TRUE, repos = BiocManager::repositories())
+          remotes::install_cran("rcmdcheck")
+        shell: Rscript {0}
+
+      - name: Check
+        env:
+          _R_CHECK_CRAN_INCOMING_REMOTE_: false
+        run: rcmdcheck::rcmdcheck(args = c("--no-manual"), error_on = "warning", check_dir = "check")
+        shell: Rscript {0}
+      
+
+      - name: Build pkgdown
+        run: |
+           PATH=$PATH:$HOME/bin/ Rscript -e 'pkgdown::build_site(".")'
+
+      # deploy needs rsync? Seems so.
+      - name: Install deploy dependencies
+        run: |
+          apt-get update
+          apt-get -y install rsync
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@releases/v3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages # The branch the action should deploy to.
+          FOLDER: docs # The folder the action should deploy.
+
+      - uses: docker/build-push-action@v1
+        with:
+          # The two entries below need to be entered as 
+          # github secrets. The "secret" names are "DOCKER_USERNAME"
+          # and "DOCKER_PASSWORD". See https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
+          # for detailed instructions. 
+          #
+          # DO NOT EDIT THESE ENTRIES HERE. Doing so will 
+          # expose your docker username and password on github.
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+          # Use the environment variable on first few lines to set repo name--just centralizes changes
+          repository: ${{ env.repo-name }}
+          tag_with_ref: true
+          tag_with_sha: true
+          tags: latest
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+inst/doc
+*~
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -0,0 +1,28 @@
+Package: BuildABiocWorkshop
+Title: Bioconductor Workshop Template and Github Actions
+Version: 0.9.0
+Authors@R: 
+    person(given = "Sean",
+           family = "Davis",
+           role = c("aut", "cre"),
+           email = "seandavi@gmail.com",
+           comment = c(ORCID = "your-orc-id-here"))
+Description: This package serves as a template for using github actions to 
+    prepare a Bioconductor Workshop package for use. In particular,
+    a pkgdown website and docker image are generated based on workflow 
+    settings. 
+License: MIT + file LICENSE
+Encoding: UTF-8
+LazyData: true
+Roxygen: list(markdown = TRUE)
+RoxygenNote: 7.1.0
+Depends: 
+    Biobase
+Suggests: 
+    knitr,
+    rmarkdown,
+    pkgdown
+URL: https://seandavi.github.io/BuildABiocWorkshop/
+BugReports: https://github.com/seandavi/BuildABiocWorkshop/issues/new/choose
+VignetteBuilder: knitr
+DockerImage: seandavi/buildabiocworkshop:latest
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,9 @@
+FROM bioconductor/bioconductor_docker:devel
+
+WORKDIR /home/rstudio
+
+COPY --chown=rstudio:rstudio . /home/rstudio/
+
+RUN Rscript -e "options(repos = c(CRAN = 'https://cran.r-project.org')); BiocManager::install(ask=FALSE)"
+
+RUN Rscript -e "options(repos = c(CRAN = 'https://cran.r-project.org')); devtools::install('.', dependencies=TRUE, build_vignettes=TRUE, repos = BiocManager::repositories())"
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,2 @@
+YEAR: 2020
+COPYRIGHT HOLDER: Sean Davis
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2020 Sean Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/NAMESPACE b/NAMESPACE
@@ -0,0 +1,2 @@
+# Generated by roxygen2: do not edit by hand
+
diff --git a/README.md b/README.md
@@ -0,0 +1,53 @@
+# BuildABiocWorkshop
+
+This package is a template for building a Bioconductor workshop. The package
+includes Github actions to:
+
+1. Set up bioconductor/bioconductor_docker:devel on Github resources
+2. Install package dependencies for your package (based on the `DESCRIPTION` file)
+3. Run `rcmdcheck::rcmdcheck`
+4. Build a pkgdown website and push it to github pages
+5. Build a docker image with the installed package and dependencies
+
+## Responsibilities
+
+This year, package authors will be primarily responsible for:
+
+1. Creating a landing site of their choosing for their workshops (a website). This website should be listed in the `DESCRIPTION` file as the `URL`.
+2. Creating a docker account and image that will contain workshop materials and the installed packages necessary to run those materials. The name of the resulting docker image, including "tag" if desired, should be listed in a non-standard tag, `DockerImage:` in the `DESCRIPTION` file. 
+
+Both of those tasks can be accomplished using the Github actions included in this template package. The vignette accompanying this package describes how to accomplish both of these tasks.
+
+## Details
+
+For detailed instructions, see the `How to build a workshop` article/vignette.
+
+## Results of successful deployment
+
+- A working docker image that contains the installed package and dependencies.
+- An up-to-date `pkgdown` website at https://YOURUSERNAME.github.io/YOURREPOSITORYNAME/
+- Docker image will be tagged with `latest`, `sha-XXXXXX` where `XXXXXX` is the hash of the current `master` commit, and `master`. 
+
+## To use the resulting image:
+
+```sh
+docker run -e PASSWORD=<choose_a_password_for_rstudio> -p 8787:8787 YOURDOCKERIMAGENAME
+```
+Once running, navigate to https://localhost:8787/ and then login with `rstudio`:`yourchosenpassword`. 
+
+To try with **this** repository docker image:
+
+```sh
+docker run -e PASSWORD=abc -p 8787:8787 seandavi/buildabiocworkshop2020
+```
+
+*NOTE*: Running docker that uses the password in plain text like above exposes the password to others 
+in a multi-user system (like a shared workstation or compute node). In practice, consider using an environment 
+variable instead of plain text to pass along passwords and other secrets in docker command lines. 
+
+
+## Whatcha get
+
+https://seandavi.github.io/BuildABiocWorkshop
+
+![dockerhub](https://github.com/seandavi/BuildABiocWorkshop/raw/master/inst/images/dockerhub_result.png)
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -0,0 +1,18 @@
+url: https://seandavi.github.io/BuildABiocWorkshop
+
+template:
+  params:
+    bootswatch: flatly
+    #ganalytics: UA-99999999-9
+
+home:
+  title: "BuildABiocWorkshop"
+  type: inverse
+
+
+navbar:
+  right:
+   - icon: fa-github
+     href: https://github.com/seandavi/BuildABiocWorkshop
+     
+
diff --git a/inst/images/dockerhub_result.png b/inst/images/dockerhub_result.png
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/vignettes/HOWTO_BUILD_WORKSHOP.Rmd b/vignettes/HOWTO_BUILD_WORKSHOP.Rmd
@@ -0,0 +1,112 @@
+---
+title: "How To Build A Workshop Package"
+subtitle: "In other words, how do I use what's here"
+author: Sean Davis^[seandavi@gmail.com]
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{How to Use this Package to Build a Bioc Workshop}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+First, this package doesn't do much except add a template Github Action to
+build all the pieces necessary for a workshop.
+
+## Quickstart
+
+- [ ] Create a repo from this template and rename it (do not fork the repository).
+- [ ] Edit `DESCRIPTION` file
+  - [ ] Change package name
+  - [ ] Change title and description
+  - [ ] Change authors
+  - [ ] Check dependencies
+  - [ ] Change DockerImage tag
+- [ ] Edit '_pkgdown.yml' and`.github/workflows/basic_checks.yaml`
+- [ ] Write a normal R package that can be installed
+- [ ] Include one or more vignettes that will constitute the workshop materials
+
+## Details
+
+To accomplish this follow each of the 7 steps below. Once your edit the yaml files, Github actions will run each time you commit to github and it creates the pkgdown website and docker image for you. 
+
+### 1. Clone this repo
+Clone this repo, fork and **rename** it, or create a repo from this template
+
+```
+git clone https://github.com/seandavi/BuildABiocWorkshop MYPKGDIR
+```
+
+### 2. Edit `DESCRIPTION` file
+
+- Change the package name to something identifiable and descriptive, ideally 
+something that will be somewhat unique. 
+- Edit the title and description as per any normal R package.
+- Update authors (unless you want me to get credit for your work).
+- Workshop packages are normal R packages, so dependencies work as usual. Append libraries to the Depends/Suggests/Imports in this package DESCRIPTION File, which includes;
+
+Depends: 
+    Biobase
+Suggests: 
+    knitr,
+    rmarkdown,
+    pkgdown
+  If your packages depend on a github R repos, be sure to specify the correct repo `username/reponame`.  Installation will deal with this. 
+ 
+- Edit the last 3 lines of the DESCRIPTION FILE, URL, BugReports and DockerImage (described in more detail below)
+
+### 3. Set up a website (Github Pages)
+
+In your repository, click on settings or url https://github.com/<github username>/<workshop repos name>/settings.  Midway down the page, in the GitHub Pages section, select source 'gh-pages branch'.  If only 'master branch' is visible, select master for now, but once Github actions runs, 'gh-pages branch' will be available and is required to render the website. 
+  
+In the DESCRIPTION file, update the URL: to the website url eg https://seandavi.github.io/BuildABiocWorkshop/
+
+### 4. Edit _pkgdown.yml
+
+Edit the file _pkgdown.yml, updating the url:, title and href: which should be your website url, title of your workshop and github repos url respectively.  You do not need to edit this file further. You do not need to add menus or links to vignettes. GitHub Actions and pkgdown will do this when it builds the website
+
+### 5. Edit `.github/workflows/basic_checks.yaml`
+
+You need a dockerhub account, which if you don't have one, can be created at hub.docker.com.  Your <docker user name> maybe different to your <gitub username name>. 
+
+You do not need to create a docker image manually. Github actions will read Dockerfile located in this template, and using the yamls files will create, build and push to dockerhub an image with your desired name. 
+
+- **You MUST change the `repository` line in this yaml file to be YOUR desired Docker image name**. 
+
+- The **image name must be in lower case**.
+
+
+
+
+```yaml
+on: [push, pull_request]
+
+env:
+  cache-version: v1
+  # Change the following line to what you want YOUR
+  # docker image to be called. Do not include 
+  # any tags--those will be added automatically
+  repo-name: seandavi/buildabiocworkshop
+```
+
+In the DESCRIPTION file, the **DockerImage: should match your desired name for a dockerhub repository**.
+
+### 6. Add "secrets" to github repo
+
+Secrets are encrypted environment variables that you create in a
+repository or organization. The secrets you create are available to
+use in GitHub Actions workflows. GitHub uses a libsodium sealed box to
+help ensure that secrets are encrypted before they reach GitHub, and
+remain encrypted until you use them in a workflow.
+ 
+See [Creating and storing encrypted secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)
+
+- `DOCKER_USERNAME`: your dockerhub username; create a dockerhub account if you do not have one
+- `DOCKER_PASSWORD`: your dockerhub password or an access token obtained from [Docker Hub][]
+
+[Docker Hub]: https://hub.docker.com/settings/security
+
+
+### 7. Edit README.md, add vignettes to vignettes folder
+Edit the README.md. and add one or more Rmd vignettes that will constitute the workshop materials. It is normal R package that should pass rcmdcheck::rcmdcheck(), and be installed using regular R package install commands.  
+
+
diff --git a/vignettes/workshop_example.Rmd b/vignettes/workshop_example.Rmd

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+YEAR: 2020`
	`2`	`+COPYRIGHT HOLDER: Sean Davis`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+# Generated by roxygen2: do not edit by hand`
	`2`	`+`