4  Publishing the data

The package now has data, a dictionary, help pages and metadata. This chapter writes the README that GitHub shows on the repository page and builds the website that presents the dataset.

4.1 Write the README

4.1.1 Create it from the template

setup_readme(has_example = TRUE)

washr writes README.Rmd from its template. The file holds the title and badges, an introduction placeholder, the installation instructions, a download table with one row per dataset and links to the CSV and XLSX exports, a section for the first dataset with its dimensions, a preview and the variable table from the dictionary, an Example section with a scaffold for a first plot, the license, and a citation section that names the version and the DOI in plain text once they exist. Without has_example = TRUE the Example section is left out.

4.1.2 Write the text

Open README.Rmd and fill in the parts that are yours.

  • The introduction. One paragraph of three to five sentences in place of “The goal of … is to”. Say who collected the data, how, when and where, and under which license or permission the source data was shared.
  • The data sentence. Complete “The dataset … contains data about”.
  • A block per further dataset. The template documents the first dataset in data/. For each further one, copy the block from its heading to the end of its variable table and replace the dataset name in the heading, in the sentence, in the preview chunk and in the filter of the variable table.
  • The example. The plot code is commented out. Fill in variables of your dataset, write readable axis labels and a title, and uncomment the block together with the library(ggplot2) line. One plot that gives a useful first look at the data is enough. Say in the text what the plot shows.

The installation instructions, the download table, the dimensions, the previews, the variable tables, the license and the citation are generated. Leave them as they are.

4.1.3 Build it

README.md is built from README.Rmd and never edited by hand:

devtools::build_readme()

The build loads the packages named in the installation chunk (dplyr, knitr, readr, stringr, gt and kableExtra), so install the ones you are missing when the build stops. Commit both README files and push. GitHub shows README.md on the repository page.

4.2 Build the website

The website is built by pkgdown from the README, the help pages and the metadata. The review standard has it deployed by a GitHub Actions workflow to the gh-pages branch of the repository, so that the built site is never committed and never goes stale. Set up the workflow first, then let washr write the configuration and build.

4.2.1 Add the deployment workflow

usethis::use_github_action("pkgdown")

The call writes the workflow .github/workflows/pkgdown.yaml. It runs on every push to the main branch, builds the site and writes it to the gh-pages branch. Nothing else changes yet.

4.2.2 Write the configuration and build the site

setup_website()

The first run writes _pkgdown.yml from the washr template, with the address of the site, the analytics header, the funding sentence in the sidebar and a reference index with one entry per dataset. Every value comes from DESCRIPTION. Then it builds the site into docs/, which takes a minute. Because the deployment workflow exists, docs/ stays in .gitignore, and the local build is a preview. Open docs/index.html in a browser to see it. Every later run keeps _pkgdown.yml as it is and rebuilds the site.

pkgdown expects the address of the site in DESCRIPTION as well, next to the repository URL. Add it, with the value of the url line of _pkgdown.yml:

desc::desc_add_urls("https://openwashdata.github.io/yourpackagename")
Note

A repository that cannot run GitHub Actions can serve the site from the main branch instead. Skip the workflow and run setup_website(). Without a workflow it removes docs from .gitignore, so that the built site is committed. In the Pages settings of the repository, choose the main branch and the /docs folder as the source. The review standard prefers the workflow, because a committed site is only as current as its last build.

4.2.3 Apply the brand

use_brand()

This copies the brand file and the logos of the openwashdata brand from the latest release of the brand repository into your package, adds them to .Rbuildignore, wires _pkgdown.yml to them and records the release in DESCRIPTION. The site now uses the openwashdata fonts and colours. Run it again after a new brand release. A run with no new release changes nothing. For a package under another organisation, the Config/washr/brand-source field in DESCRIPTION names the brand repository to copy from, or none.

4.2.4 Check, commit and publish

Run devtools::document(), devtools::check() and devtools::install() once more, then commit everything and push. The push starts the pkgdown workflow on GitHub, which builds the site and writes it to the gh-pages branch. The branch appears with the first run, after a few minutes.

Then open the repository on GitHub, go to “Settings” and “Pages”, and under “Build and deployment” choose “Deploy from a branch”, with the gh-pages branch and the root folder as the source. The site is live at the address in _pkgdown.yml a minute later, and every later push rebuilds it.

Reports about the package in the openwashdata look, as PDF or Word documents, use the quarto-owd Quarto extension. It reads the brand file that use_brand() installed.