Clean up README and vignettes

coatless · coatless · commit 64f7976956aa · 2025-03-31T19:50:47.000-07:00
diff --git a/README.Rmd b/README.Rmd
@@ -14,7 +14,7 @@ knitr::opts_chunk$set(
 )
 ```
 
-# multideploy <img src="man/figures/multideploy-logo.svg" align="right" height="139" />
+# multideploy <img src="man/figures/multideploy-logo.svg" align="right" width="139" alt="a hex logo for the multideploy R package" />
 
 <!-- badges: start -->
 [![R-CMD-check](https://github.com/coatless-rpkg/multideploy/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/coatless-rpkg/multideploy/actions/workflows/R-CMD-check.yaml)
@@ -27,7 +27,9 @@ The `multideploy` package provides tools for deploying file changes across multi
 
 You can install the development version of `multideploy` from [GitHub](https://github.comcoatless-rpkg/multideploy) with:
 
-```r
+```{r}
+#| label: setup-readme
+#| eval: false
 # install.packages("remotes")
 remotes::install_github("coatless-rpkg/multideploy")
 ```
@@ -38,19 +40,28 @@ remotes::install_github("coatless-rpkg/multideploy")
 GitHub API authentication and querying. Before using `multideploy`, make sure
 you have a GitHub Personal Access Token (PAT) set up:
 
-```r
+```{r}
+#| label: auth-session-readme
+#| eval: false
 # Set GitHub PAT (or use .Renviron)
 Sys.setenv(GITHUB_PAT = askpass::askpass("What is your GitHub Personal Access Token (PAT)?"))
 ```
 
-It's recommended to store your PAT in your `.Renviron` file rather than in your code.
+For regular use, it's recommended to add your PAT to the git credential system
+through the `gitcreds` package:
+
+```{r}
+#| label: auth-credentials-readme
+#| eval: false
+gitcreds::gitcreds_set()
+```
 
 ## Quick Start Example
 
 Here's an example showing how to deploy a standardized CI workflow file to multiple repositories using `multideploy`:
 
 ```{r}
-#| label: quick-example
+#| label: quick-example-readme
 #| eval: false
 library(multideploy)
 
@@ -83,7 +94,7 @@ step through the additional features of the package within this section.
 List and filter repositories across users or organizations:
 
 ```{r}
-#| label: repo-listing
+#| label: repo-listing-readme-demo
 #| eval: false
 # Get all public repositories for a user
 user_repos <- repos("username", type = "public")
@@ -100,7 +111,7 @@ my_orgs <- orgs()
 Deploy individual files or sets of files to multiple repositories:
 
 ```{r}
-#| label: file-deploy
+#| label: file-deploy-readme-demo
 #| eval: false
 # Deploy a single file
 file_deploy("local/path/file.R", "remote/path/file.R", repos)
@@ -129,7 +140,7 @@ pr_create(
 Preview changes before making them:
 
 ```{r}
-#| label: dry-run
+#| label: dry-run-readme-demo
 #| eval: false
 # Preview changes without making them
 file_deploy("local/file.R", "remote/file.R", repos, dry_run = TRUE)
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# multideploy <img src="man/figures/multideploy-logo.svg" align="right" height="139" />
+# multideploy <img src="man/figures/multideploy-logo.svg" align="right" width="139" alt="a hex logo for the multideploy R package" />
 
 <!-- badges: start -->
 
@@ -36,8 +36,12 @@ sure you have a GitHub Personal Access Token (PAT) set up:
 Sys.setenv(GITHUB_PAT = askpass::askpass("What is your GitHub Personal Access Token (PAT)?"))
 ```
 
-It’s recommended to store your PAT in your `.Renviron` file rather than
-in your code.
+For regular use, it’s recommended to add your PAT to the git credential
+system through the `gitcreds` package:
+
+``` r
+gitcreds::gitcreds_set()
+```
 
 ## Quick Start Example
 
diff --git a/vignettes/multideploy.Rmd b/vignettes/multideploy.Rmd
@@ -17,33 +17,33 @@ knitr::opts_chunk$set(
 
 ## Introduction
 
-The `multideploy` package provides a streamlined way to deploy file changes
+The `{multideploy}` package provides a streamlined way to deploy file changes
 across multiple GitHub repositories. Whether you're managing standardized CI/CD
 configurations, common utility scripts, code style definitions, or any other 
-files that should be consistent across repositories, `multideploy` helps
+files that should be consistent across repositories, `{multideploy}` helps
 automate this process.
 
 This vignette will guide you through the main functionality of the package with
 practical examples.
 
 ## Setup and Authentication
 
-First, load the multideploy package:
+First, load the `{multideploy}` package:
 
 ```{r}
-#| label: setup
+#| label: setup-vignette
 #| eval: FALSE
 library(multideploy)
 ```
 
-Before using `multideploy`, you need to authenticate with GitHub. The package
+Before using `{multideploy}`, you need to authenticate with GitHub. The package
 uses the [`gh`](https://github.com/r-lib/gh) package for authentication, which 
 looks for a [GitHub Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) in the `GITHUB_PAT` or
 `GITHUB_TOKEN` environment variables. This token can be set directly within the
 R script via:
 
 ```{r}
-#| label: auth
+#| label: auth-session-vignette
 #| eval: FALSE
 # Set GitHub PAT (or better, use .Renviron)
 Sys.setenv(GITHUB_PAT = askpass::askpass("What is your GitHub Personal Access Token (PAT) ?"))
@@ -52,22 +52,12 @@ Sys.setenv(GITHUB_PAT = askpass::askpass("What is your GitHub Personal Access To
 For regular use, it's recommended to add your PAT to the git credential system
 through the `gitcreds` package:
 
-```r
+```{r}
+#| label: auth-credentials-vignette
+#| eval: false
 gitcreds::gitcreds_set()
 ```
 
-Alternatively, you can set the PAT directly in your `.Renviron` file by running:
-
-```r
-file.edit("~/.Renviron")
-```
-
-Then, type: 
-
-```bash
-GITHUB_PAT=your_github_pat_here
-```
-
 Your PAT needs appropriate permissions to access and modify repositories. 
 At a minimum, you'll need:
 
@@ -81,7 +71,7 @@ At a minimum, you'll need:
 The `repos()` function allows you to list repositories for a user or organization:
 
 ```{r}
-#| label: repos
+#| label: repos-list-vignette
 #| eval: FALSE
 # List repositories for a user
 user_repos <- repos("username")
@@ -101,7 +91,7 @@ head(api_repos)
 If you're a member of multiple organizations, you can list them with:
 
 ```{r orgs}
-#| label: orgs
+#| label: orgs-list-vignette
 #| eval: FALSE
 my_orgs <- orgs()
 print(my_orgs)
@@ -114,7 +104,7 @@ print(my_orgs)
 You can retrieve the content of a file from a GitHub repository:
 
 ```{r}
-#| label: file-content
+#| label: file-content-vignette
 #| eval: FALSE
 # Get content of a file
 workflow_file <- file_content("username/repo", ".github/workflows/ci.yml")
@@ -128,7 +118,7 @@ cat(workflow_file$content)
 To create or update a file in a repository:
 
 ```{r}
-#| label: file-update
+#| label: file-update-vignette
 #| eval: FALSE
 # Update a file
 result <- file_update(
@@ -141,14 +131,14 @@ result <- file_update(
 
 ## Deploying Files Across Repositories
 
-The core functionality of `multideploy` is deploying files across multiple repositories. This can be done in two ways:
+The core functionality of `{multideploy}` is deploying files across multiple repositories. This can be done in two ways:
 
 ### Direct File Deployment
 
 Deploy a single file to multiple repositories:
 
 ```{r}
-#| label: file-deploy
+#| label: file-deploy-vignette
 #| eval: FALSE
 # Get repositories
 repos <- repos("orgname", filter_regex = "^api-")
@@ -170,7 +160,7 @@ print(results)
 For changes that require review, you can create pull requests:
 
 ```{r}
-#| label: file-mapping-and-pull-requests
+#| label: file-mapping-and-pull-requests-vignette
 #| eval: FALSE
 # Create a mapping of files to deploy
 mapping <- file_mapping(
@@ -199,7 +189,7 @@ print(pr_results)
 You can deploy all files from a directory while preserving their structure:
 
 ```{r}
-#| label: dir-mapping
+#| label: dir-mapping-vignette
 #| eval: FALSE
 # Create mapping from a directory
 workflow_mapping <- file_mapping(
@@ -224,7 +214,7 @@ pr_create(
 Before making actual changes, you can preview them using dry run mode:
 
 ```{r}
-#| label: dry-run
+#| label: dry-run-vignette
 #| eval: FALSE
 # Preview file deployment without making changes
 dry_results <- file_deploy(
@@ -243,7 +233,7 @@ print(dry_results)
 You can combine repository filtering with deployment to target specific subsets of repositories:
 
 ```{r targeting}
-#| label: target-repos
+#| label: target-repos-vignette
 #| eval: FALSE
 # Get all organization repositories
 all_repos <- repos("orgname")
@@ -296,7 +286,7 @@ example script that updates CI/CD workflows and deploys configuration files to
 all repositories in an organization:
 
 ```{r}
-#| label: deployment-script
+#| label: deployment-script-vignette
 #| eval: FALSE
 library(multideploy)
 
@@ -334,7 +324,7 @@ If you want to deploy the files directly without creating pull requests, you can
 use the following snippet to directly deploy the configuration files:
 
 ```{r}
-#| label: deployment-script-custom
+#| label: deployment-script-custom-vignette
 #| eval: FALSE
 # Directly deploy config files
 for (local_file in names(config_mapping)) {
@@ -352,6 +342,6 @@ for (local_file in names(config_mapping)) {
 
 # Fin
 
-The `multideploy` package streamlines the process of maintaining consistent 
+The `{multideploy}` package streamlines the process of maintaining consistent 
 files across multiple GitHub repositories. By automating deployment, you can 
 ensure standardization while saving significant time and effort.
