Merge pull request #1 from ucla-imls-open-sci/workbench

Workbench

_config.yml

@@ -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"

docs/carpentries-workbench/callout_blocks.md

@@ -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)

docs/carpentries-workbench/carpentries-workbench.md

@@ -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.

docs/carpentries-workbench/sandpaper.md

@@ -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.