From 1a04df17785c04fe5c898fac7d08e35f53e34b08 Mon Sep 17 00:00:00 2001 From: seankross Date: Thu, 20 Apr 2023 15:26:06 -0700 Subject: [PATCH 1/2] some doc stuff --- _pkgdown.yml | 5 +- docs/404.html | 16 +- docs/LICENSE-text.html | 14 +- docs/articles/configuration.html | 18 +- docs/articles/github-repo.html | 39 ++- docs/articles/index.html | 16 +- docs/articles/kyber.html | 16 +- docs/articles/quick-cohort-setup.html | 332 +++++++++++++++++++++++ docs/authors.html | 14 +- docs/deps/data-deps.txt | 4 +- docs/index.html | 16 +- docs/pkgdown.yml | 5 +- docs/reference/add_code_of_conduct.html | 14 +- docs/reference/add_gitignore.html | 14 +- docs/reference/add_team_members.html | 14 +- docs/reference/add_team_to_repo.html | 14 +- docs/reference/call_agenda.html | 14 +- docs/reference/create_github_clinic.html | 14 +- docs/reference/create_readme.html | 14 +- docs/reference/create_team.html | 14 +- docs/reference/index.html | 14 +- docs/reference/init_repo.html | 14 +- docs/reference/kyber_file.html | 16 +- docs/reference/md_agenda.html | 14 +- docs/reference/pipe.html | 14 +- docs/reference/short_names.html | 14 +- docs/search.json | 2 +- docs/sitemap.xml | 3 + vignettes/github-repo.Rmd | 2 - vignettes/quick-cohort-setup.Rmd | 199 ++++++++++++++ 30 files changed, 619 insertions(+), 280 deletions(-) create mode 100644 docs/articles/quick-cohort-setup.html create mode 100644 vignettes/quick-cohort-setup.Rmd diff --git a/_pkgdown.yml b/_pkgdown.yml index 674fb2a..30709c9 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,4 +1,7 @@ url: "https://openscapes.github.io/kyber/" template: bootstrap: 5 - +navbar: + left: + - text: "Quick Cohort Setup" + href: articles/quick-cohort-setup.html diff --git a/docs/404.html b/docs/404.html index bbb1d93..dda39e6 100644 --- a/docs/404.html +++ b/docs/404.html @@ -13,8 +13,8 @@ - - + + @@ -41,17 +41,7 @@

The token should appear as a string with about 40 random alphanumeric characters that start with ghp_. Copy the string from GitHub before running the code below. You will be prompted to enter the diff --git a/docs/articles/github-repo.html b/docs/articles/github-repo.html index 2c1fff2..5889879 100644 --- a/docs/articles/github-repo.html +++ b/docs/articles/github-repo.html @@ -15,8 +15,8 @@ - - + +

@@ -104,7 +94,28 @@

Creating the Repository

Each Champions Cohort has its own GitHub repository. The name of the repository should match the corresponding cohort_name in -the Cohort Registry. The init_repo()

+the Cohort Registry. The init_repo() +function in the code below will do the following:

+
    +
  1. It checks to see if the GitHub repository you are trying to create +already exists. If it does exist, it will result in an error.
    2. +
  2. It tries to initialize a GitHub repository on your computer. If that +repository already exists in the path argument, it will +result in an error. No repository will have been created on GitHub.
    3. +
  3. It will then create the local Git repository, add a code of conduct +(via add_code_of_conduct()), add a .gitignore +file (via add_gitignore()), and then git add +and git commit those files before git push-ing +those files to GitHub.
    4. +
  4. Finally it will create a README.Rmd file in the +repository for you to edit.
    5. +
+
+library(kyber) 
+
+repo_name <- "2021-ilm-rotj"
+
+repo_path <- init_repo(repo_name)
diff --git a/docs/articles/index.html b/docs/articles/index.html index 90a839a..69fabe5 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -1,5 +1,5 @@ -Articles • kyberArticles • kyber @@ -19,17 +19,7 @@ diff --git a/docs/articles/kyber.html b/docs/articles/kyber.html index 1c33189..477117d 100644 --- a/docs/articles/kyber.html +++ b/docs/articles/kyber.html @@ -15,8 +15,8 @@ - - + +
+ + + + +
+
+

Quick Start Guide

+ + + +
quick-cohort-setup.Rmd
+
+ + + +
+

Configuration +

+

Using Kyber requires more configuration than most R packages since +Kyber functions automate processes on GitHub that you would normally do +by hand.

+

First, make sure that you have googlesheets4 installed +and that you have authorized your computer to read from Google Sheets. +Run the following to test your configuration settings:

+
+library(googlesheets4)
+
+cohort_registry_url <- "https://docs.google.com/spreadsheets/d/1Ys9KiTXXmZ_laBoCV2QWEm7AcnGSVQaXvm2xpi4XTSc/"
+
+read_sheet(cohort_registry_url, sheet = "test-sheet")
+
+library(usethis)
+library(gitcreds)
+
+create_github_token(
+  scopes = c("repo", "user", "gist", "workflow", "admin:org")
+)
+
+gitcreds_set()
+
+
+

Example Workflow +

+

This workflow often happens in 4 separate stages:

+
    +
  1. create the repo and readme (pre-cohort)
    2. +
  2. create github-clinic files (days before GitHub Clinic +in Call 2)
    3. +
  3. create github team and add usernames (day before Clinic, when we +have all usernames)
    4. +
  4. create agenda documents before each Cohort Call
    5. +
+

For creating the GitHub Team and adding usernames, Kyber requires you +to set up a GitHub Personal Access Token with scopes for +repo and admin:org. See the GitHub +PAT documentation for more information about how to generate your +PAT. You can create your PAT with +usethis::create_github_token() with their defaults, plus +admin:org. Please make sure that you do not share your PAT +or commit it to a Git repository, since anyone with your PAT can act as +you on GitHub.

+
+

Create GitHub repo +

+
+library(kyber) 
+library(rmarkdown)
+library(tibble)
+library(fs)
+
+repo_name <- "2021-ilm-rotj"
+
+# This will open a README.Rmd for you to edit
+repo_path <- create_repo(repo_name)
+
+# Then render the README.Rmd to README.md
+render(path(repo_path, "README.Rmd"))
+
+# We still need to work out the next part of the workflow and the extent to
+# which it should be automated, but I imagine something like:
+#
+# 1. Move README.Rmd out of this repository to another repository that perhaps 
+# only contains README.Rmds.
+# 2. Git add, commit, and push in the repo that only contains README.Rmds.
+# 3. Git add, commit, and push in this repository.
+
+
+

GitHub Clinic - Generate Markdown Files for Each Participant +

+

Clone the Cohort Repo to RStudio, then run the following code. +Detailed instructions of what this looks like:

+
    +
  1. Open RStudio, and create a new script (temporary, you’ll deleted it +but it’s a nicer place to work)
    2. +
  2. Copy the following into the script, then delete the examples “Erin, +Julie”. You’ll keep the _demo.md, which is what you’ll demo +live.
    3. +
  3. Go to the ParticipantsList, and copy the 2 first and last +columns
    4. +
  4. Back in RStudio, put your cursor inside the “tribble” parentheses, +then, in the Addin menu in the top of RStudio, select “Paste as +Tribble”!
    5. +
  5. Then, double-check the column headers - they are likely not +first and last as is written in the +kyber::short_names call. The easiest thing is to update the +column names in the kyber::short_names code before running +(for example: +kyber::short_names(cohort$First.Name, cohort$Last.Name) +
    6. +
+
library(stringr)
+library(datapasta) # install.packages("datapasta")
+library(kyber) ## remotes::install_github("openscapes/kyber")
+library(here)
+library(fs)
+
+## use `datapasta` addin to vector_tribble these names formatted from the spreadsheet!
+cohort <- c(tibble::tribble(
+                      ~first,             ~last,
+                      "_demo",       "",                      
+                      "Erin",        "Robinson",
+                      "Julie",         "Lowndes"
+               )
+)
+
+## create .md files for each Champion
+kyber::short_names(cohort$first, cohort$last) |>
+   create_github_clinic(here())
+   
+## copy trailhead image into parent folder
+trailhead_png <- system.file("kyber-templates", 
+                               "horst-champions-trailhead.png", package = "kyber")
+fs::file_copy(trailhead_png, here())
+

You’ll now have .md files for each participant in the cohort! Any +duplicate names with have a _LastInitial. Check by clicking +into the github-clinic folder and opening a file.

+

Now, commit and push the Markdown files in the +github-clinic folder plus the +`horst-champions-trailhead.png in the top-level folder to GitHub.com. +Don’t push the .gitignore or .rproj since they’re not relevant for the +Clinic. (You can do Command-A to select all files and then unclick those +2 you don’t want).

+
+
+

Create GitHub team, add usernames +

+
    +
  1. Open RStudio, and create a new script (temporary, you’ll deleted it +but it’s a nicer place to work)
    2. +
  2. Paste the following in it and review the code. You may already have +a GitHub PAT set; there is more information at the top of the README +about it.
    3. +
  3. Run this code first as-is with the example usernames in the +members variable to check -
    4. +
  4. Check that the example usernames were added in the Cohort GitHub: go +to github.com/openscapes/cohort-name > Settings > Collaborators +and Teams
    5. +
  5. If the team was created with the username and appears in the repo, +woohoo!
    6. +
  6. Open the ParticipantsList and copy the GitHub username column, +including the header.
    7. +
  7. In RStudio, put your cursor after members <- and use +the datapasta Addin > Paste As Tribble to paste the +usernames into the members variable, deleting the previous +example user.
    8. +
  8. After pasting in the R script, rename the header as “username” (no +spaces or asterices)
    9. +
  9. Run the following code again and check that everyone was added!
    10. +
  10. Finally, in the ParticipantList, highlight all usernames we’ve added +in green. This helps us know who else to add during the live clinic +session.
    11. +
+
+## First make sure you have a GitHub PAT set. If you need one, here's what you'd do:
+# usethis::create_github_token() ## use their defaults plus `admin:org`
+# Sys.setenv(GITHUB_PAT = "ghp_0id4zkO4GqSuEsC6Zs22wf34Y0u3270") 
+
+library(kyber) 
+library(rmarkdown)
+library(tibble)
+library(fs)
+library(datapasta)
+
+## create naming for GitHub - do this once!
+repo_name <- "2022-nasa-champions"
+team_name <- paste0(repo_name, "-cohort")
+create_team(team_name, maintainers = "jules32", org = "openscapes")
+
+## create member variable - do this twice (first as test!)
+## this is where you'll use datapasta and run everything below
+members <- tibble::tribble(
+     ~username,
+     "eeholmes"
+  )
+
+add_team_members(team_name, members = members$username, org = "openscapes")
+add_repo_to_team(repo_name, team_name, org = "openscapes")
+

Yay! Now all to do is to highlight the usernames in green in the +ParticpantList for our bookkeeping!

+
+
+

Agendas +

+
kyber::call_agenda(
+    registry_url = "https://docs.google.com/spreadsheets/d/1Ys9KiTXXmZ_laBoCV2QWEm7AcnGSVQaXvm2xpi4XTSc/edit#gid=942365997", 
+    cohort_id = "2022-nasa-champions", 
+    call_number = 3)
+

Then, to move this to a Google Doc and fine-tune formatting, follow +these notes (as of July 14, 2022):

+
    +
  • In RStudio, Knit (or PreviewHTML) the resulting +agenda.md and copy-paste the result into a Google Doc +(example: 03_CallAgenda [ 2022-noaa-afsc ]. You might need to to expand +the knitted preview into the browser to get it to copy/paste correctly +into Google Docs
    • +
  • Move Google Doc to Openscapes Workspace folder +Openscapes_CohortCalls [ year-cohort-name ].
    • +
  • Select all (cmd-A) and change font to Open Sans
    • +
  • Make p1 opening text 9 point font (the text above horizontal line +& Call title)
    • +
  • Make Header 1 font 18, bold; update heading 1 to match (see +screenshot below; Stef notes “update heading to match” has not been +working in these docs)
    • +
  • Make Header 2 font 14, bold; update heading 2 to match
    • +
  • Select all (cmd-A), then: +
      +
    • “add space” then “remove space after paragraph” +throughout to make spacing a little more cozy (yes seems odd to do and +undo, but it works)
      • +
    • “add space” then “remove space before paragraph” +throughout to make spacing a little more cozy
      • +
    +
    • +
  • Review doc and fix any further font weirdness
    • +
  • Add page numbers
    • +
+

How to “update heading 1 to match”: (Stef notes this +has not been working in these docs) In Google Doc, to update a text +style (headings, normal text, with font type, size etc), highlight a +section with the style you want, click the styles dropdown shown in the +screenshot, and select e.g. “Update Heading 1 to match”. Double check +the doc because we’ve noticed it missed some in an agenda.

+
+

Screen Shot 2022-07-14 at 5 50 28 PM

+
+
+
+
+
+ + + +
+

+

Developed by Sean Kross, Julia Lowndes.

+
+ +
+

+

Site built with pkgdown 2.0.7.

+
+ +
+
+ + + + + + + diff --git a/docs/authors.html b/docs/authors.html index 0d25eff..d4394f9 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -1,5 +1,5 @@ -Authors and Citation • kyberAuthors and Citation • kyber @@ -19,17 +19,7 @@