forked from carpentries/workbench
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.qmd
165 lines (113 loc) · 6.9 KB
/
index.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
---
title: The Carpentries Workbench
subtitle: An accessible lesson infrastructure
---
The Workbench is a [complete redesign of The Carpentries lesson
websites](https://carpentries.org/blog/2020/08/lesson-template-design/), with
new features prioritising accessibility and navigation for Learners and
Instructors. By separating the tools from the content of the lesson, The
Workbench makes it easier for Maintainers and Authors to focus on the content of
the lesson and not the tooling. To try it out, head over to [the Resources
section](#resources).
::: {.callout-tip}
## Testimonials
> [The Workbench] has provided an easy way to navigate the various parts of the lesson and
> switch between or share the training content including instructor notes
> seamlessly.
>
> --- Malvika Sharan (from [Celebrating The Carpentries Workbench (2023-08-21)](https://carpentries.org/blog/2023/08/celebrating-carpentries-workbench/))
> [editing a lesson] was pretty easy. I was doing this at the end of a long day and my brain
> was only half on. It seemed to just work.
>
> --- Anonymous Maintainer (from [Reflecting on our first Alpha Test of the Lesson Infrastructure Redesign (2021-07-06)](https://carpentries.org/blog/2021/07/infrastructure-testing/))
:::
<figure style='text-align: center'>
<p>
<img src="fig/hex-collection.jpeg" width="50%" alt="three isometric hex badges for The Carpentries Workbench representing the packages sandpaper, pegboard, and varnish. Each badge is styled to look like a tiny workshop working on a wooden carpentries logo with the package namesake highlighted.">
<div class='column-screen-inset' style='text-align: left'>
<img src="fig/lc-workbench.png" width="23%" alt="screenshot of the 'Navigating the Filesystem' episode of the Library Carpentry Shell lesson">
<img src="fig/dc-workbench.png" width="23%" alt="screenshot of the 'Introduction to R' episode of the Library Carpentry R for Social Scientists lesson">
<img src="fig/swc-workbench.png" width="23%" alt="screenshot of the 'Navigating Files and Directories' episode of the Software Carpentry Shell lesson">
<img src="fig/cp-workbench.png" width="23%" alt="screenshot of the 'Building Skill with Practice' episode of the Instructor Training lesson">
</div>
</p>
</figure>
## Resources
The Workbench is built using the [R language](https://r-project.org) as a suite
of three R packages: [{sandpaper}], [{pegboard}], and [{varnish}] that work
together with R's robust publishing ecosystem and [pandoc](https://pandoc.org)
manage and deploy Carpentries Lesson websites written in Markdown or R Markdown.
### Usage
::: {.panel-tabset}
#### Within R
To preview a lesson that uses The Workbench, open R (or RStudio), [install The
Workbench](#installation), and run the following command to start a live preview
that will update while you edit:
```r
sandpaper::serve()
```
#### From the command line
To preview a lesson that uses The Workbench, make sure you [install The
Workbench](#installation), and run the following command to start a live preview
that will update while you edit:
```bash
R -e 'sandpaper::serve(quiet = FALSE, port = "3435")'
```
You can then open your browser to <http://localhost:3435> preview your lesson as
you edit.
:::
For more guidance on The Workbench, including how create a new lesson, run
accessibility tests, and more, consult our [Guides](#guides)
### Installation
To install the workbench, make sure you have a working version of R and
pandoc/RStudio installed (see [the workbench setup instructions for
details](https://carpentries.github.io/sandpaper-docs/)).
::: {.callout-tip collapse='true'}
#### Setup with Anaconda
Thanks to Travis Wrightsman for [providing the instructions to setup for
anaconda](https://github.com/carpentries/workbench/issues/50). These lines
will set up an anaconda environment that includes all the dependencies you need
to use The Workbench.
```sh
conda create -n workbench 'git>=2.28' 'r-base>=3.6' 'pandoc>=2.11' pkg-config libxslt
conda activate workbench
R -e 'install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"), \
repos = list(carpentries="https://carpentries.r-universe.dev/", CRAN="https://cloud.r-project.org"))'
```
:::
From there, you can install the workbench packages and their dependencies from
our [Carpentries R Universe](https://carpentries.r-universe.dev) inside of R:
```r
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
repos = c("https://carpentries.r-universe.dev/", getOption("repos")))
```
### Updating
To update workbench packages, you can use the same command as you did to install
your packages:
```r
install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
repos = c("https://carpentries.r-universe.dev/", getOption("repos")))
```
### Guides
- [Glossary](reference.html#glossary) A glossary of terms for The Workbench.
- [Official Workbench Documentation](https://carpentries.github.io/sandpaper-docs): written using The Workbench, this guide provides everything you need to get started using The Workbench.
- [Collaborative Lesson Development Training](https://carpentries.github.io/lesson-development-training/): Material for a three day workshop teaching good practices in lesson design and open source collaboration skills
### Tools
- [{sandpaper}]\: User interface and engine for the workbench
- [{pegboard}]\: Validation and parsing of lesson components
- [{varnish}]\: HTML, CSS, and JavaScript templates
- [(carpentries/actions)](https://github.com/carpentries/actions#readme): GitHub Actions for Workbench Workflows
- [(carpentries/lesson-transition)](https://github.com/carpentries/lesson-transition): Tool for automated transition from styles-based lessons to Workbench.
### Templates
- [R Markdown Lesson Template](https://github.com/carpentries/workbench-template-rmd)
- [Markdown Lesson Template](https://github.com/carpentries/workbench-template-md)
### Inspired Examples
These are examples of lessons developed with The Workbench since the initial announcement:
- Toby Hodges, Mateusz Kuzak, Aleksandra Nenadic, Sarah Stevens---[Collaborative Lesson Development Training](https://carpentries.github.io/lesson-development-training/)
- Saranjeet Kuar, Achintya Rao, Heather Turner, Aman Goel---[R's Bug Tracking](https://contributor.r-project.org/r-bug-tracking-lesson/)
- Saba Ferdous, David Pérez-Suárez---[Learn To Discover---Basic Python](https://learntodiscover.github.io/Basic_Python/) (note---this uses a custom fork of sandpaper, and varnish to run python)
- Philipp Matthias Schäfer---[GitLab Novice](https://zedif.github.io/gitlab-novice/)
- Michael Culshaw-Maurer---[Rewrite of the R Ecology Lesson](https://www.michaelc-m.com/Rewrite-R-ecology-lesson/)
[{sandpaper}]: https://carpentries.github.io/sandpaper/ "User interface and engine for the workbench"
[{pegboard}]: https://carpentries.github.io/pegboard/ "Validation and parsing of lesson components"
[{varnish}]: https://carpentries.github.io/varnish/ "HTML, CSS, and JavaScript templates"