Documentation & Literate Programming

Session 2

September 5, 2024

Review of last lesson

• What questions do you have?
• What happened as you were trying to organize a research compendium?
  • Victories?
  • Stumbling blocks?

Literate Programming

• Code is interwoven with human-language notes, comments, and documentation.

• Some kind of “engine” handles executing the code and weaving together prose, code, and results.

• Allows for extended comments on code and reproducible reports and manuscripts

Quarto

What is Quarto?

“An open-source scientific and technical publishing system”

• Mix markdown, code, and the output of code

• Produce beautifully formatted documents in a variety of formats (html, Word, pdf, etc.)

• Data analysis notebook

• Presentations for collaborators

• Reproducible manuscripts

• …and more!

How does Quarto work?

• Command line tool, not an R package, but works well with RStudio

knitr or jupyter are used to convert code chunks into markdown, pandoc converts markdown into output

Create a new Quarto document

In RStudio: File > New File > Quarto Document

Click “Render” to see the rendered output

Anatomy of a .Qmd file

myreport.qmd

---
title: "My Report"
author: "Eric Scott"
format: 
  html:
    toc: true
---

```{r}
#| label: load-packages
#| include: false

library(tidyverse)
library(gapminder)
```

## Data

My data source is the [gapminder](https://www.gapminder.org/) dataset.

```{r}
head(gapminder)
```

If this looks familiar to RMarkdown users, that’s because Quarto was built on lessons learned from developing RMarkdown. It includes all the features of RMarkdown and more.

YAML

“Yet another markup language”

• Commonly used for configuration files

• key: value pairs

• Nesting indicated by indentation with 2 spaces

Markdown

Markdown is a “markup language” that let’s you write plain text to indicate formatting. For example:

• **bold text** becomes bold text

• ~~strikethrough~~ becomes strikethrough

• $E = mc^2$ becomes \(E = mc^2\)

• [link](https://www.google.com) becomes link

• `code()` becomes code()

Check Help > Markdown quick reference in RStudio

Common markdown pitfalls

Spaces between elements matter! How would you fix each of these?

###Heading 3

###Heading 3

Colors:
- red
- green

Colors: - red - green

1.Number one
2.Number two

1.Number one 2.Number two

Common markdown pitfalls

Spaces within elements don’t matter!

This     sentence still  gets    rendered  correctly!

This sentence still gets rendered correctly!

Single line breaks don't separate paragraphs.
See?

You need two line breaks for that!

Single line breaks don’t separate paragraphs. See?

You need two line breaks for that!

Code

• Code chunks can be R, Python, or other languages

• If R, code is executed by knitr engine, otherwise by jupyter

• Chunk options as YAML (#| key: value) modify execution behavior or output formatting

Our turn

• Create a new Quarto Document

• Practice editing and rendering

• Explore the Visual editor mode

• Add citations and cross-references

README.md

• Your README.md uses a simple version of markdown, and will get formatted nicely once we put it on GitHub
• You can use the visual editor on .md files also
• If you need to have code executed in your README, you can use format: gfm for “GitHub Flavored Markdown”

Learning More & Getting Help

• Getting started with Quarto tutorial

• Quarto for Academics talk

• Full Quarto guide and reference (searchable!)

• #quarto channel in UA Data Science Slack

• Rendering to GitHub Flavored Markdown

Your tasks

• Use Quarto to create a report for your compendium

• Try converting a R script with a lot of comments into a Quarto document instead