diff --git a/_config.yml b/_config.yml index a2f9021..bbfe41d 100644 --- a/_config.yml +++ b/_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" \ No newline at end of file diff --git a/assets/img/workbench/Q_O.png b/assets/img/workbench/Q_O.png new file mode 100644 index 0000000..0920380 Binary files /dev/null and b/assets/img/workbench/Q_O.png differ diff --git a/assets/img/workbench/challenge.png b/assets/img/workbench/challenge.png new file mode 100644 index 0000000..c1a4786 Binary files /dev/null and b/assets/img/workbench/challenge.png differ diff --git a/assets/img/workbench/default_callout.png b/assets/img/workbench/default_callout.png new file mode 100644 index 0000000..e84def8 Binary files /dev/null and b/assets/img/workbench/default_callout.png differ diff --git a/assets/img/workbench/draft_after.png b/assets/img/workbench/draft_after.png new file mode 100644 index 0000000..53906c0 Binary files /dev/null and b/assets/img/workbench/draft_after.png differ diff --git a/assets/img/workbench/draft_before.png b/assets/img/workbench/draft_before.png new file mode 100644 index 0000000..e104e02 Binary files /dev/null and b/assets/img/workbench/draft_before.png differ diff --git a/assets/img/workbench/draft_command.png b/assets/img/workbench/draft_command.png new file mode 100644 index 0000000..e78400f Binary files /dev/null and b/assets/img/workbench/draft_command.png differ diff --git a/assets/img/workbench/pop_out.png b/assets/img/workbench/pop_out.png new file mode 100644 index 0000000..44e982c Binary files /dev/null and b/assets/img/workbench/pop_out.png differ diff --git a/assets/img/workbench/sandpaper_console.png b/assets/img/workbench/sandpaper_console.png new file mode 100644 index 0000000..c38e6c3 Binary files /dev/null and b/assets/img/workbench/sandpaper_console.png differ diff --git a/assets/img/workbench/sandpaper_serve.png b/assets/img/workbench/sandpaper_serve.png new file mode 100644 index 0000000..f3dad26 Binary files /dev/null and b/assets/img/workbench/sandpaper_serve.png differ diff --git a/docs/carpentries-workbench/callout_blocks.md b/docs/carpentries-workbench/callout_blocks.md new file mode 100644 index 0000000..bf05355 --- /dev/null +++ b/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. + + Note that you don't need to have exactly 3 colons, you need ***AT LEAST*** 3 colons in order to create a callout block. + +``` +::: 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. + +Note that the solution and hint tabs will be closed at first. + +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) \ No newline at end of file diff --git a/docs/carpentries-workbench/carpentries-workbench.md b/docs/carpentries-workbench/carpentries-workbench.md index b7f2fac..cac0dc1 100644 --- a/docs/carpentries-workbench/carpentries-workbench.md +++ b/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. \ No newline at end of file diff --git a/docs/carpentries-workbench/sandpaper.md b/docs/carpentries-workbench/sandpaper.md index d6c76f9..34a5f91 100644 --- a/docs/carpentries-workbench/sandpaper.md +++ b/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. \ No newline at end of file