-
Notifications
You must be signed in to change notification settings - Fork 0
/
make_readme.qmd
225 lines (149 loc) · 8.92 KB
/
make_readme.qmd
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
---
title: "Make a README"
lang: en
engine: knitr
---
## What does a README contain?
Once you have prepared your project and settled on a license, it is time to add a final touch. Imagine returning to your project in five years, having forgotten most of the details of what you did exactly. What would be useful to know in order to quickly understand what is going on in the project? This is what needs to be described in the README. While you could just start writing along, most READMEs have some sections in common which we describe below.
Name
: How is the project called?
Badges/Project Status
: Badges typically report quick facts, like [whether the project is actively maintained](https://www.repostatus.org/), [how many dependencies it has](https://tinyverse.netlify.app/), or [whether it has been published in a package repository](https://www.r-pkg.org/services#badges). Sometimes, the license, any associated DOIs, or quality metrics like code coverage by unit tests are communicated via badges as well.
Description
: What is the project about? What are its features? Why was it created?
Visuals
: Is there anything you can show that demonstrates how the project can be used? Screenshots or other visuals can make the README more appealing.
Installation/Dependencies
: What steps need to be taken to run the project? What software needs to be installed? Mention all dependencies here that are not explicitly managed by `renv`, such as the system dependencies of R packages as well as the version of Quarto. An R package's system dependency is any additional software that you need to install on your computer in order to use a particular R package. For example, the R package [`reticulate`](https://rstudio.github.io/reticulate/) allows to run Python code from within R. However, in order to actually use it, one has to additionally install Python itself as it does not come together with `reticulate` -- rather, it is a system dependency. See @sec-dependencies for additional information.
Usage
: Which files does the project contain? How are they organized? How can one run the project -- is there a master script or a particular order in which any scripts need to be executed? How long does it take to run all scripts? Is there additional documentation available?
Support
: Do you offer support or help, for example, via GitHub discussions or a mailing list?
Contributing
: If the project is active: Can other people contribute? How? Do you accept contributions? Do you review issues? This section is sometimes outsourced into a file called `CONTRIBUTING.md`.
Authors
: Who was involved in creating this project? This involves you, your co-authors, and anybody you accepted contributions from.
Citation
: Is there a recommended way to cite this project? Is there a published article associated with it that you would like to have cited? We recommend to increase citability by using the [CodeMeta generator](https://codemeta.github.io/codemeta-generator/) to create a file called `codemeta.json`. Alternatively, one can also use the R package [`codemetar`](https://docs.ropensci.org/codemetar/) to create this file. Then, put it into the project folder. Another common standard is the [Citation File Format](https://citation-file-format.github.io/) (CFF), which is an equally valid option.
License
: Under which licenses are the works in this project available?
## Installation/Dependencies {#sec-dependencies}
An overview over the system dependencies of R packages can be created using the function `pak::pkg_sysreqs()`. In combination with `renv`, we can obtain the system dependencies of all R packages in the current project:
```{.r filename="Console"}
pak::pkg_sysreqs(renv::dependencies()$Package)
```
The output may look like the following:
```txt
── Install scripts ───────────────────────
dnf install -y make pandoc
── Packages and their system dependencies
fs – make
knitr – pandoc
rmarkdown – pandoc
sass – make
```
We can see that `make` and `pandoc` were identified as system dependencies. One can obtain their version by running them with the `--version` argument:
```{.bash filename="Terminal"}
make --version
pandoc --version
```
We also know that we need Quarto to create the PDF, so let's find out its version as well:
```{.bash filename="Terminal"}
quarto --version
```
If you installed `apaquarto` or any other Quarto extension, one can query their versions as follows:^[Luckily, the extensions are included in the project folder, so technically their version is already recorded in the project's files.]
```{.bash filename="Terminal"}
quarto list extensions
```
Finally, we know that we installed a $\TeX$ distribution to create the PDF, so let's find out its version by running:
```{.bash filename="Terminal"}
quarto check
```
The output is quite long and it might look slightly different for you, but the relevant sections are the following:
```txt
[✓] Checking tools....................OK
TinyTeX: v2024.09
Chromium: (not installed)
[✓] Checking LaTeX....................OK
Using: TinyTex
Path: /home/r155953/.TinyTeX/bin/x86_64-linux
Version: 2024
```
## Create It!
Create your README now as the file `README.md`. If you feel stuck, you can have a look at the following examples:
::: {#tip-name .callout-tip collapse="true"}
### Name
```{.md .code-overflow-wrap filename="README.md"}
# Penguin Paper
```
:::
::: {#tip-project-status .callout-tip collapse="true"}
### Badges/Project Status
```{.md .code-overflow-wrap filename="README.md"}
[](https://www.repostatus.org/#unsupported)
```
:::
::: {#tip-description .callout-tip collapse="true"}
### Description
```{.md .code-overflow-wrap filename="README.md"}
This project contains the Quarto manuscript of our study on penguins. It is written in R and uses `renv` to track its dependencies.
```
:::
::: {#tip-installation .callout-tip collapse="true"}
### Installation/Dependencies
``````{.md .code-overflow-wrap filename="README.md"}
## Dependencies
This manuscript requires the following system software to be installed. In addition, we provide the version numbers this manuscript has last been run with:
- [Quarto](https://quarto.org/docs/download/) 1.6.9
- GNU Make 4.4.1
- Pandoc 3.3
- TinyTeX 2024.09
- [R](https://cloud.r-project.org/) 4.4.1
On Fedora Linux, Make and Pandoc can be installed as follows:
```bash
dnf install -y make pandoc
```
Quarto and R can be installed using the links provided. TinyTeX can be installed using Quarto by entering the following into the terminal:
```bash
quarto install tinytex
```
All R packages that this project requires are managed using [`renv`](https://cran.r-project.org/package=renv). Therefore, `renv` needs to be installed first, by entering the following in the R console:
```r
install.packages("renv")
```
Next, one can open a new R session in the root directory of this project and run the following, which should install all required R packages at their recorded versions:
```r
renv::restore()
```
``````
:::
::: {#tip-usage .callout-tip collapse="true"}
### Usage
`````{.md .code-overflow-wrap filename="README.md"}
## Usage
The most important file in this project is `Manuscript.qmd` which contains the text of the article as well as the code for its computations. It is accompanied by the following files:
- `Bibliography.bib`: bibliographic references used in the manuscript
- `Data.csv`: a data set containing the simplified `palmerpenguins` data created using `write.csv(palmerpenguins::penguins, "dat.csv", row.names = FALSE)`
- `data_dictionary.html`: a dictionary to the data file, created using `create_data_dictionary.R`
The folder `_extensions` contains the `apaquarto` extension which is used to typeset the PDF accoording to APA guidelines.
The manuscript can be rendered to PDF using the following command:
```bash
quarto render Manuscript.qmd
```
``````
:::
::: {#tip-citation .callout-tip collapse="true"}
### Citation
```{.md .code-overflow-wrap filename="README.md"}
## Citation
Please cite this draft as follows:
> Zerna & Scheffel (2024): "A Study on Penguins: A Minimal Reproducible Example". Unpublished manuscript.
```
:::
::: {#tip-citation .callout-tip collapse="true"}
### License
```{.md .code-overflow-wrap filename="README.md"}
## License
The manuscript file and the bibliograhpic references are made available by us under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The data set by Kristen Gorman has been published under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). `apaquarto` has also been published under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). All other files in this project are available under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/).
```
:::