generated from just-the-docs/just-the-docs-template
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1 from ucla-imls-open-sci/workbench
Workbench
- Loading branch information
Showing
13 changed files
with
157 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,11 @@ | ||
title: Just the Docs Template | ||
title: UCLA IMLS Documentation | ||
description: A starter template for a Jeykll site using the Just the Docs theme! | ||
theme: just-the-docs | ||
|
||
repository: "ucla-imls-open-sci/UCLA-imls-docs" | ||
url: https://ucla-imls-open-sci.info/UCLA-imls-docs | ||
|
||
aux_links: | ||
Template Repository: https://github.com/ucla-imls-open-sci/UCLA-imls-docs | ||
|
||
back_to_top: true | ||
back_to_top_text: "Back to top" |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
--- | ||
title: Callout Blocks | ||
layout: default | ||
parent: Carpentries Workbench | ||
nav_order: 2 | ||
--- | ||
|
||
The Carpentries Workbench comes with a customized version of Pandoc. What is pandoc? Pandoc is a tool that allows for custom callout blocks. | ||
These blocks can be used in a variety of ways from challenge questions to discussion points. A formative list of all the [Callout Blocks](https://carpentries.github.io/sandpaper-docs/component-guide.html) supported by the Carpentries are found in that link. | ||
|
||
## Callout Blocks | ||
|
||
Callout blocks are created through ***fenced divs***. These are a pair of 3 or more ***:::*** at the beginning and end of what you are | ||
trying to callout. | ||
|
||
![Default Callout Block]({{ site.baseurl }}/assets/img/workbench/default_callout.png) | ||
|
||
The code for this callout block goes as follows: | ||
|
||
``` | ||
::: callout | ||
## Callout Block | ||
This is what a default Callout block looks like | ||
::: | ||
``` | ||
|
||
The structure of the callout block starts with at least 3 colons (:::) followed by the type of callout that you want to use. You can find a list of | ||
supported callout blocks [here](https://carpentries.github.io/sandpaper-docs/component-guide.html). After that comes the content followed by an ending set of colons. | ||
|
||
<i> Note that you don't need to have exactly 3 colons, you need ***AT LEAST*** 3 colons in order to create a callout block. </i> | ||
|
||
``` | ||
::: Name of the callout block you want to use | ||
## Heading | ||
Content | ||
::: <- ending set of colons | ||
``` | ||
|
||
## Special Callout Blocks | ||
|
||
### Questions and Objectives | ||
Every episode should contain a ***questions*** and ***objectives*** callout block at the start. This outlines an overview for the episode that is | ||
being taught. They are displayed side by side in the browser and will look like this. | ||
|
||
![Questions and Objective Callout Block]({{ site.baseurl }}/assets/img/workbench/Q_O.png) | ||
|
||
The code for this looks like this: | ||
|
||
``` | ||
::: questions | ||
- How do you write a lesson using Markdown and `{sandpaper}`? | ||
::: | ||
::: objectives | ||
- Explain how to use markdown with The Carpentries Workbench | ||
- Demonstrate how to include pieces of code, figures, and nested challenge blocks | ||
::: | ||
``` | ||
|
||
*Note that these two callout blocks are special and have to follow each other in order to be displayed properly. Another thing | ||
to note is that they are using markdown's bullet point format putting '-' in the beginning of each statement.* | ||
|
||
### Challenges | ||
Challenges should be frequently utilized throughout a lesson. The Carpentries has a special Challenge block that looks like this. | ||
|
||
![Challenge Block]({{ site.baseurl }}/assets/img/workbench/challenge.png) | ||
|
||
The ***Challenge*** block is accompanied by a ***solution*** block with the ability to add a ***hint*** block as well. the code for that | ||
looks something like this. | ||
|
||
``` | ||
:::::::::::::::::::::::::::::::::: challenge | ||
## Challenge title (optional) | ||
Challenge | ||
::::::::::::::::::: hint | ||
your hint | ||
::::::::::::::::::: | ||
::::::::::::::::::: solution | ||
### Title (optional) | ||
Solution | ||
::::::::::::::::::: | ||
:::::::::::::::::::::::::::::::::: | ||
``` | ||
|
||
In this callout block, we nest the ***solution*** and ***hint*** blocks within the ***challenge*** block. This is so the heirarchy is | ||
preserved. Another thing to note is the Title in ***solution*** block. If you choose to include a title then the title would replace the | ||
***SOLUTION*** tab with the title that you give it. Another thing is that a ***challenge*** block should be accompanied by a ***solution*** block but that is optional. The ***hint*** block is completely optional and up to user descretion. | ||
|
||
<i>Note that the solution and hint tabs will be closed at first. </i> | ||
|
||
There are several other callout blocks that are supported and you can find more information about them [here](https://carpentries.github.io/sandpaper-docs/component-guide.html) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,13 @@ | ||
--- | ||
title: Carpentries Workbench | ||
layout: home | ||
layout: default | ||
permalink: /docs/carpentries-workbench | ||
has_children: true | ||
--- | ||
|
||
# Carpentries Workbench | ||
|
||
This is the workbench that the lesson authors will use. You guys can familiarize yourself with the workbench by going through these guides. | ||
[A dive into the Workbench](https://carpentries.github.io/sandpaper-docs/) and [Curriculum Development with the workbench](https://cdh.carpentries.org/). | ||
These guides offer an introduction into the workbench and how it works and should be used. The following documentation is something you can | ||
look back at to get a better feel and understanding of the important elements in the workbench. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,60 @@ | ||
--- | ||
title: Into Sandpaper | ||
layout: home | ||
layout: default | ||
parent: Carpentries Workbench | ||
nav_order: 1 | ||
--- | ||
|
||
## What is Sandpaper? | ||
|
||
Sandpaper is the an R Studio package that is used in the Carpentries Workbench. It is used to run, preview, and build Lessons locally. | ||
It comes with a suite of commands that help you build, preview, and run the site. You can preview these commands in the R Studio Console by | ||
typing out "sandpaper::" . A list of commands should appear after the "::" . Below we will document and describe several key commands. | ||
Each command also has a short description that you can read. | ||
![R Studio Console Accepts Sandpaper Commands]({{ site.basurl }}/assets/img/workbench/sandpaper_console.png) | ||
|
||
### sandpaper::create_lesson() | ||
|
||
This command in R Studio will create an empty Carpentries Workbench in the path provided in its argument. This is a good message to use in R Studio | ||
if you want to create a new lesson using the Workbench. An example would be ***sandpaper::create_lesson("/filepath/Carpentries Guide")***. This command | ||
would create a new workbench with the name **Carpentries Guide** in the path you specified. | ||
|
||
|
||
|
||
### sandpaper::draft_episode_md() & sandpaper::draft_episode_rmd() | ||
|
||
This command takes in 1 input, that being the title of the episode you want to create. You would use this command when you have a | ||
draft for an episode but don't yet want to publish it. It will create a template for the episode under the episodes/ folder and you can | ||
edit it from there like a normal lesson. To do so, you will run the following command in the RStudio console, ***sandpaper::draft_episode_md("Episode Title")***. After you are completed and want to move the episode into the lesson, you will have to use the ***sandpaper::move_episode("Episode Name")*** | ||
command. This command will help you move the episode into the config file without you having to manually do it. | ||
Of course, if you want to create an R Markdown episode use the ***rmd()*** otherwise use the ***md()***. | ||
|
||
#### Before Episode Creation | ||
![Episode Folder Before]({{ site.baseurl }}/assets/img/workbench/draft_before.png) | ||
|
||
#### Episode Creation Command | ||
![Episode Folder]({{ site.baseurl }}/assets/img/workbench/draft_command.png) | ||
|
||
#### After Episode Creation | ||
![Episode Folder After]({{ site.baseurl }}/assets/img/workbench/draft_after.png) | ||
|
||
### sandpaper::create_episode_md() & sandpaper::create_episode_rmd() | ||
|
||
These set of commands have the same functionality as the commands above except for the fact that you don't need to use the ***move_episode()*** function. | ||
These commands will automatically create a new episode and input it into the config file so that you will be able to directly see any changes made | ||
to it. | ||
|
||
### sandpaper::serve() | ||
|
||
Sandpaper::serve() is a command that will build and display your site in the bottom-right viewer of R Studio. (Tip: You can pop this view out | ||
into it's own window) This command will incrementally update your Lesson as you make any changes. It is great for viewing changes in a quick manner | ||
without having to constantly running ***sandpaper::build_lesson()*** or other build commands. | ||
|
||
![Sandpaper::serve() and its Output]({{ site.baseurl }}/assets/img/workbench/sandpaper_serve.png) | ||
|
||
If you look closely you a small icon to the right of the broom in the viewer window. If you click on that you will be able to pop-out the | ||
episode into a browser window. | ||
|
||
![Pop-out Icon]({{ site.baseurl }}/assets/img/workbench/pop_out.png) | ||
|
||
There are more ***sandpaper::*** commands if you browse around in the R Studio console but these are the most important ones that will be used. |