4  Publishing Your Dataset

4.1 Creating and Editing the README

To start documenting your dataset for publication, you first need to set up a README file.

4.1.1 Initialize the README

In your R console, within the project directory, run the following command to create a README file:

setup_readme()

If you want the README to include an Example section with a scaffold for a first plot of your data, use this command instead:

setup_readme(has_example = TRUE)

The template documents the first data object in data/. When your package holds several, copy the data section once per further object.

4.1.2 Editing the README

Locate the README.Rmd file in your project directory and open it. Edit each section of the README to provide relevant information about your package. Typical sections include:

  • Package Name and Brief Description
  • Installation Instructions
  • Basic Usage
  • Features
  • Example

4.1.3 Creating a Data Visualization

In the “Example” section of your README, it’s helpful to include at least one plot that showcases your data. The section written by setup_readme(has_example = TRUE) holds a commented scaffold for it. For instance, using ggplot2, you could create a plot like this (adapt it to fit your specific data):

library(ggplot2)
library(yourpackagename)

ggplot(your_data, aes(x = variable1, y = variable2)) +
  geom_point() +
  theme_minimal() +
  labs(title = "Example Plot from YourPackageName")

4.1.4 Building the README

Once you’ve completed editing the README, convert it to a Markdown file by running:

devtools::build_readme()

This will generate a README.md file, which GitHub displays on your repository’s main page.

4.1.5 Updating GitHub

After building the README, go to the “Git” tab in RStudio. Stage the newly created or modified README files, commit them with a message such as “Add and update README,” and push the changes to GitHub.

4.2 Setting Up the Package Website

To enhance your package’s accessibility, you can create a website for it.

4.2.1 Initializing the Website

Run the following command in your R console:

setup_website()

The first run writes _pkgdown.yml from the openwashdata template and builds the site into docs/. Every later run keeps your _pkgdown.yml as it is and rebuilds the site, so there is nothing to answer.

4.2.2 Applying the openwashdata brand

To give the site the openwashdata fonts and colors, run:

use_brand()

This copies the brand file and the logos from the central brand repository into your package and points _pkgdown.yml at them. Run it again whenever the brand changes.

4.2.3 Document, Check, and Install the Package

Ensure your package is up-to-date by running the following commands:

devtools::document()
devtools::check()
devtools::install()

These commands generate the latest documentation, check the package for issues, and install it locally.

4.2.4 Preparing for GitHub Pages

To host the package website on GitHub Pages, Git has to track the built site. setup_website() removes the docs line from .gitignore for you, so the docs/ folder is tracked. Check that the line is gone before you commit.

4.2.5 Updating GitHub with Website Files

Go to the “Git” tab in RStudio. You should now see new files in the docs/ folder and the updated .gitignore file. Stage these changes, commit them with a message like “Add pkgdown website files,” and push the updates to GitHub.

4.2.6 Setting Up GitHub Pages

To activate the website, open your GitHub repository in a web browser. Go to “Settings” > “Pages.” Under “Source,” select the branch where your docs/ folder resides (usually “main” or “master”) and set the folder to /docs. Finally, click “Save.”

Your package website will now be live at https://yourusername.github.io/yourrepositoryname/.

Remember, if you make significant changes to your package or documentation, you may need to rebuild the website by running pkgdown::build_site() and pushing the updated docs/ folder to GitHub.