-
Notifications
You must be signed in to change notification settings - Fork 4
/
README.Rmd
124 lines (93 loc) · 6.45 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
---
output:
md_document:
variant: gfm
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
# pkgdown template <img src="man/figures/logo.png" align="right" style="padding: 10px"/>
<!-- badges: start -->
[](https://github.com/nmfs-fish-tools/pkgdownTemplate/releases)
[](https://github.com/nmfs-fish-tools/pkgdownTemplate/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
This is a template for a NMFS branded GitHub repository, R package, and pkgdown website. It will have a NMFS palette, appropriate license and disclaimer, and a NMFS footer with logo. It has GitHub Actions that will automatically rebuild the site whenever the files are changed. The instructions will use the **usethis** and **pkgdown** packages. So install those.
If you already have an R package that you just want to add a site for, please use [these instructions](https://noaa-fisheries-integrated-toolbox.github.io/resources/workshops/NOAA-pkgdown/).
## Step 1 Make sure the package builds
1. <span title="To clone a GitHub repository, copy the URL of the repo, then click the + sign in the top right and choose 'Import repository'. Import the repository into your own GitHub account; you probably want to give it the name of your R package. Then clone YOUR copy of pkgdownTemplate onto your computer. Work within that local clone of your pkgdownTemplate copy."><a href="">Clone</a></span> this GitHub repository and then open the new repository (on
your computer).
2. Set-up your RStudio project to use Roxygen for documentation and
NAMESPACE
- Tools > Project Options… > Build Tools Click the checkbox that
says “Build documentation with Roxygen”.
- The Configure popup box for Roxygen will probably appear, if not
click the Configure button. Check all the checkboxes.
1. On the Build tab, click Install and Restart to make sure your copy of {pkgdownTemplate} builds.
2. On the Build tab, click Check to make sure the package passes all the checks.
3. Type the code `pkgdown::build_site()` and make sure the {pkgdown} site builds.
Note the steps above are to make sure your computer is set up to build and
check packages. As long as you haven’t editted the package yet, it will
build and pass check.
## Step 2 Customize your R package
1. Edit the DESCRIPTION file (change Title, Description, urls for repo,
Authors)
2. Add any required packages to Depends (or Imports\* or Suggests\*).
3. Edit the Readme file.
- Does your Readme contain R code? Edit the Readme.Rmd file and <span title="In RStudio, you will see the knit button when you open Readme.Rmd"><a href="">knit</a></span> to create the Readme.md file. You will need to re-knit Readme.Rmd every time you change the Rmd file.
- Do you want to make sure your Readme file uses the most up to date Disclaimer and footer from FIT? Then you will also need to use the Rmd file.
- If your Readme does not include R code and you don't need to keep your {pkgdown} site synced with the FIT disclaimers, footer and license, then you can delete Readme.Rmd and just use Readme.md. In this case, you do not need to knit Readme.md. {pkgdown} will use the md file directly.
- Note, make sure to change `nmfs-fish-tools` in the badge section to your repo name to the name of your GitHub account or GitHub organization.
6. Add your functions to the `R` folder. There are some template
functions there already.
5. Don’t touch the Rd files in the `man` folder. Roxygen2 will make your Rd files.
## Step 3 Customize your **pkgdown** site and build
1. *Structure of the upper navbar* Edit `_pkgdown.yml` in the `pkddown`
folder to change the look of the upper navbar. There are endless
options. Find examples from other peoples’ {pkgdown} sites. Make sure to change
all the URLs in the `_pkdown.yml` file.
2. Update your logo. The logo is in `man/figures/logo.png`. If you change the name of the logo file, then change the where the logo file is referenced in the Readme file (line 3).
3. After updating your logo, run `pkgdown::build_favicon()` to remake the favicons.
4. Add material to the `docs` folder as needed. See the example for the
References tab in the `_pkgdown.yml`. This won't be needed for all R packages. It depends what reference material you are including.
5. Build your {pkgdown} site with `pkgdown::build_site()`.
## Step 4 Make some vignettes (optional)
Vignettes are longform examples and are Rmd files in the `vignettes`
folder. Easiest way to start a new vignette is
`usethis::use_vignette("vignettename")`.
## Step 5 Make your site live on GitHub
1. Push the local changes to your R package (the pkgdownTemplate you copied) to GitHub.
2. Click on Settings for your repository.
3. Scroll way down to the GitHub Pages section.
4. In the **Source** section, change branch to Main and folder to
`docs`. There are other ways to set up GitHub Pages but this will
get you started.
5. I always add my GitHub Pages URL to the repo description (on right
when on your main repo page).
## NMFS Branding
{pkgdownTemplate} has the following branding elements.
1. `extra.css` in the `pkgdown` folder sources the **nmfspalette** css.
This get you the colors.
2. The `Readme.md` file sources the NMFS Disclaimer and footer with
NMFS logo from the [FIT
Resources](https://github.com/nmfs-fish-tools/Resources).
3. The LICENSE is set to that used by [FIT
packages](https://github.com/nmfs-fish-tools).
## GitHub Actions and Badges
In the `.github` folder is just one action, to run R CMD check on the
package.
## Readme File
**pkgdown** uses `Readme.md` but to pull in the Disclaimer and footer
from FIT, which migh change in the future, you need a Rmd file. When you update the `Readme.Rmd` file,
**you need to remember to knit the file** to update `Readme.md`. You could make a GitHub Action to do this.
<!-- Do not edit below. This adds the Disclaimer and NMFS footer. -->
****
```{r add-disclaimer, echo=FALSE, results='asis'}
url <- "https://raw.githubusercontent.com/nmfs-fish-tools/Resources/master/Disclaimer.md"
childtext <- readLines(url)
cat(childtext, sep="\n")
```
****
```{r footer, echo=FALSE, results='asis'}
url <- "https://raw.githubusercontent.com/nmfs-fish-tools/Resources/master/footer.md"
childtext <- readLines(url)
cat(childtext, sep="\n")
```