-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
93 lines (63 loc) · 4.43 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
---
output:
md_document:
variant: gfm
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
# DataProduct <img src="man/figures/logo.png" align="right" style="padding: 10px"/>
<!-- badges: start -->
[](https://github.com/RVerse-Tutorials/DataProduct/releases)
[](https://github.com/RVerse-Tutorials/DataProduct/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
This is a template for a NMFS branded R package and pkgdown website. It will have a NMFS palette, appropriate license and disclaimer, and a NMFS footer with logo.
The instructions will use the **usethis** and **pkgdown** packages. So install those.
## Step 1 Make sure the package builds
1. Clone 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.
3. On the Build tab, click Install and Restart to make sure it builds.
4. On the Build tab, click Check to make sure it passes all the checks.
5. Type the code `pkgdown::build_site()` and make sure the **pkgdown** building works. If on RStudio Cloud, you will need to use `pkgdown::build_site(override = list(destination = "~/docs"))` to see the webpage.
Note steps 3 and 4 are to make sure your computer is set up to build and check packages. As long as you haven't edited the package yet, it will build and pass check.
## Step 2 Customize your 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.Rmd file.
4. Add your functions to the R folder. There are some template functions there already.
5. Don't touch the man folder. Roxygen2 will make your Rd files.
## Step 3 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 4 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.
2. Update your logo and favicons. Logo is in `man/figures`. After updating run `pkgdown::build_favicon()` to remake the favicons.
3. Add material to the `docs` folder as needed. See the example for the References tab in the `_pkgdown.yml`.
4. Build your site with `pkgdown::build_site()`.
## Step 5 Make your site live on GitHub
1. Push the changes to GitHub.
2. Click on Settings for the 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
This template has the following branding elements.
1. `extra.css` in the `pkgdown` folder sources the **nmfspalette** css. This get you the colors.
2. The `Readme.Rmd` 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, you need a Rmd file. When you update the `Readme.Rmd` file, **you need to remember to knit the file** to update `Readme.md`.
<!-- 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")
```