**Get started with OTTR Advanced -- filing a PR from your computer**: If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts.
If you have an interest in utilizing GitHub (or already possess knowledge in this area), we suggest engaging with GitHub and Git beyond the GitHub website for creating your pull requests. @@ -192,7 +183,7 @@ of handling files. If you are not new to GitHub, then we recommend skipping this section and jumping to the [`Checks on the Pull Request` section](#checks-on-the-pull-requests). -## Cloning with Git +**1. Cloning with Git** In the GitHub workflow (excluding the Entry-Level writing method), files exist online (remote) and on your computer (local). @@ -222,8 +213,7 @@ pasting is advisable because any little typo will inhibit cloning. Now you are ready to click `Clone the repository`! It will ask you if you'd like to `Open Now`, click that. - -## Create a new branch +**2. Create a new branch** Handling branches is where you unleash the real benefit of GitHub, but it can be confusing at first. @@ -260,8 +250,7 @@ that the cursor is blinking in. In our example, we are calling it Now we can add/edit/rename currently existing files in our new branch, knowing that the content and code in the `main` branch is safe. - -## Committing changes +**3. Committing changes** Adding changes to a branch is called making `commits`. To modify any files in a branch we have to first 1) Make our changes as we normally @@ -283,8 +272,7 @@ If we want to add these file changes to our current branch, we need to Great! Now the changes you've made have been added to your local branch. - -## Pushing changes +**4. Pushing changes** Note that when you've committed your changes locally (on your computer), those changes won't be on the online version of your repository. To get them to the @@ -302,9 +290,7 @@ origin in the dropdown menu and click `Submit`.  -- -# Open a pull request {#open-a-pull-request} +
**Open a pull request**
After a variable number of commits, your branch, perhaps called `a-new-branch` or any other new branch you might have made, is a @@ -336,9 +322,7 @@ banner message, where there is a button that says  -
-
-
-
- After you click on `Compare & pull request` you'll be taken to a screen where you can add information about your changes. After you are done writing your description, click `Create Pull Request`! (If you don't @@ -369,14 +351,15 @@ steps.  -
+
+Click here if you don't see the pull request message!!!
+Click here if you don't see the pull request message!!!
Note that sometimes if you have used the same branch multiple times you may need some extra steps to create a pull request. This will involve @@ -353,8 +337,6 @@ work on. Be careful that is the branch you intend.- After you click on `Compare & pull request` you'll be taken to a screen where you can add information about your changes. After you are done writing your description, click `Create Pull Request`! (If you don't @@ -369,14 +351,15 @@ steps.  -
+
-# Checks on the pull requests +## OTTR Checks on pull requests Once your pull request is open, the OTTR GitHub Actions checks will begin. These checks will generate reports as comments on your pull request. - +
Read these comments to begin addressing the problems with more commits
to your branch.
@@ -406,11 +389,11 @@ If you encounter situations where a spelling report or URL report doesn't look a
-
+
-# Adding new pages +## Adding new pages Adding new chapters to your OTTR websites requires some specific steps in addition to what we've discussed here. diff --git a/getting_started.Rmd b/getting_started.Rmd index eec9785..8586291 100644 --- a/getting_started.Rmd +++ b/getting_started.Rmd @@ -30,8 +30,8 @@ If you are not familiar with **Git and GitHub**, we recommend going through thes We offer two suggested approaches for creating content, based on your comfort and interest level in using Git and GitHub: -- [OTTR Entry Level](https://www.ottrproject.org/writing_content.html#ottr-entry-level): If you are not interested in delving into GitHub, you can use this version, which is entirely conducted through the GitHub web browser. -- [OTTR Advanced](https://www.ottrproject.org/writing_content.html#ottr-advanced): If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts. +- **OTTR Entry Level**: If you are not interested in delving into GitHub, you can use this version, which is entirely conducted through the GitHub web browser. +- **OTTR Advanced**: If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts. If you choose to use our OTTR Advanced guidance, you will need a method for working with Git. @@ -66,23 +66,7 @@ In particular, the rendered preview on pull requests won't work, but you can alt After creating your repository, you will find that issues related to starting your course have been automatically generated and filed in your repository. To begin the setup process, navigate to the Issues tab and follow the instructions provided in those issues. - -### 5. Add jhudsl-robot as a collaborator - -\*You can skip this step if your course is in the `jhudsl` organization. - -To enable the full functionality of [GitHub Actions](https://github.com/jhudsl/OTTR_Template/wiki/How-to-set-up-and-customize-GitHub-actions-robots) in this repository, it is necessary to grant appropriate permissions. To achieve this, you should add `jhudsl-robot` as a collaborator to your repository with write permissions. - -In your repository, go to your `Settings` > `Collaborators & Teams` and click on `Add people`. -In the pop up window, search for and add `jhudsl-robot`. - -
-
-If shown the option, choose the `write` option then click `Add jhudsl-robot to this repository`. Otherwise, just click `add`.
-
-
-
-### 6. In personal repositories: check your settings
+### 5. Check your repository GitHub Action settings
In case you have a personal repository or an organization that hasn't utilized GitHub Actions previously, it is important to verify if workflow actions have been enabled.
@@ -95,7 +79,7 @@ Then click `Save`.
-### 7. Set up your GitHub personal access token
+### 6. Set up your GitHub personal access token
The OTTR robots require certain permissions to execute certain actions.
@@ -110,12 +94,14 @@ If you have organization admin privileges and plan on making multiple courses wi
All of your GitHub Actions should now be capable of running without any issues. If you encounter any problems, please report your issue to the main OTTR repository [here](https://github.com/jhudsl/OTTR_Template/issues/new?assignees=&labels=bug&projects=&template=course-problem-report.md&title%5B%5D=Problem).
-### 8. Set up GitHub Pages
+### 7. Set up GitHub Pages
+
+You'll need to set this up so that your website or course will be published to a URL!
In your repository, go to `Settings` > `Pages`.
- Under `Source`, pick `Deploy fom a branch`
-- Under `Branch`, pick `main` and choose `/docs`.
+- Under `Branch`, pick `main` and choose `/docs`.
- Then click `Save`.
- Lastly, check the box that says `Enforce HTTPS` at the bottom of this page.
@@ -132,7 +118,7 @@ For more information about GitHub Pages we recommend you refer to the GitHub doc
**Warning**: If you go to your URL right now (before you've pushed any file changes) you might see a 404 error because nothing has been triggered to be rendered. You can check the URL after you file your first pull request (which we will guide you through [in the next section](https://github.com/jhudsl/OTTR_Template/wiki/Start-editing-your-course).
-### 9. Enroll your repository for OTTR updates
+### 8. Enroll your repository for OTTR updates (Not required but highly encouraged)
This OTTR templates (https://github.com/jhudsl/OTTR_Template_Website) are always a work in progress.
We are working on adding more features and smoothing out bugs as we go. This is also why [your feedback is greatly appreciated](https://github.com/jhudsl/OTTR_Template/issues/new/choose).
@@ -166,9 +152,9 @@ _If you have any questions about the implications of any of these updates or fil
-### Methods of writing content +### Create your website or course -Now you need to decide wheyher you want to build a course or a website and follow those instructions! +Now you need to decide whether you want to build a course or a website and follow those instructions! - [Make an OTTR Website](https://www.ottrproject.org/editing_website.html) - [Make an OTTR Course](https://www.ottrproject.org/writing_content_courses.html) diff --git a/ottr-fy.Rmd b/ottr-fy.Rmd index 1042c8f..e7d3964 100644 --- a/ottr-fy.Rmd +++ b/ottr-fy.Rmd @@ -21,11 +21,11 @@ This set of steps also assumes you are more familiar with GitHub. ### Step 1: Add OTTR files to your current repository -Navigate to the top of your repository and [download this file](https://raw.githubusercontent.com/jhudsl/OTTR_Template/main/scripts/ottr-fy.R). +Navigate to the top of your repository and [download this file](https://github.com/jhudsl/ottr-reports/blob/main/scripts/ottr-fy.R). You can do this by using wget, or by just using the link above and saving it as `ottr-fy.R` in the top of your repository. ``` -wget 'https://raw.githubusercontent.com/jhudsl/OTTR_Template/main/scripts/ottr-fy.R' +wget 'https://github.com/jhudsl/ottr-reports/blob/main/scripts/ottr-fy.R' ``` You've downloaded a script that will download the necessary files to run OTTR in your repository. Take a look at the filenames of what will be downloaded to make sure that you won't accidentally overwrite any of your repository's existing files. @@ -38,17 +38,11 @@ You've downloaded a script that will download the necessary files to run OTTR in - `.github/workflows/render-all.yml` - `.github/workflows/delete-preview.yml` - `.github/workflows/docker-build.yml` -- `scripts/git_repo_check.R` -- `scripts/make_screenshots.R` -- `scripts/quiz-check.R` -- `scripts/spell-check.R` -- `scripts/url-check.R` -- `assets/toc_close.css` #### Files you'll need to edit to customize \* These files also will not be downloaded if you already have set up your repository as a bookdown website and specify this in the upcoming command. -- `_bookdown.yml` +- `_bookdown.yml` or `_site.yml` for a website/course respectively - `_output.yml` - `book.bib` - `assets/big-image.html` @@ -59,7 +53,7 @@ You've downloaded a script that will download the necessary files to run OTTR in - `config_automation.yml` - `assets/style.css` -Run this this script from your command line if your repository is not already a bookdown website. +Run this this script from your command line if your repository is not already a bookdown website. ``` Rscript ottr-fy.R ``` @@ -83,19 +77,15 @@ If they do not automatically start running, you may also want to check in your ` Check your files on this pull request your files and that nothing horrible has happened to your original files (like being overwritten or deleted). -### 2. Add your Rmd or md files to the `_bookdown.yml` file +### 2. Add your Rmd or md files to the `_bookdown.yml` or `_site.yml` file You will almost certainly find that the `Render preview` check will fail (and possibly the spelling and URL checks). -One reason that this will fail is that you will need to edit `_bookdown.yml` to list your Rmds (or mds) in the order they should appear in the course. ([See this section](https://www.ottrproject.org/customize-robots.html#Pull_request_checks:) for more information about these checks and what they are) - -[Follow these instructions](https://www.ottrproject.org/writing_content.html#Step_2_Add_the_name_of_your_new_chapter_to_your__bookdownyml_file) to add your Rmds and mds to the _bookdown.yml file. +One reason that this will fail is that you will need to edit `_bookdown.yml` `_site.yml` to list your Rmds (or mds) in the order they should appear in the course. ([See this section](https://www.ottrproject.org/customize-robots.html#Pull_request_checks:) for more information about these checks and what they are) Make sure to commit this to your branch. -You will also likely want to update your `_output.yml` file. [Read here](https://bookdown.org/yihui/bookdown/output-formats.html) for more about how to customize this `_output.yml` file. - *\ Note! Don't merge this pull request before you finish adding a few settings as described in this next step. ### 3. Set up your repository with the proper settings -From here, you can follow the rest of the steps described in the [Getting Started section](https://www.ottrproject.org/getting_started.html#5_Add_jhudsl-robot_as_a_collaborator). +From here, you can follow the rest of the steps described in the [Getting Started section](https://www.ottrproject.org/getting_started.html#Starting_a_new_OTTR_websitecourse). diff --git a/writing_content_courses.Rmd b/writing_content_courses.Rmd index 0f76c25..50ae43a 100644 --- a/writing_content_courses.Rmd +++ b/writing_content_courses.Rmd @@ -3,7 +3,6 @@ title: "Start writing content" output: html_document: toc: true - toc_float: true editor_options: markdown: wrap: 72 @@ -31,25 +30,17 @@ them. They enable OTTR to test your proposed changes for potential issues such as broken URLs or spelling errors. Importantly, pull requests facilitate discussions with others regarding proposed changes. - - -## Method of writing content - -We have two recommended ways of writing content that is based on your -comfort and interest level in using Git and GitHub: - -- [OTTR Entry Level](#ottr-entry-level): If you are not interested in delving into GitHub, you can use this version, which is entirely conducted through the GitHub web browser. -- [OTTR Advanced](#ottr-advanced): If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts. - - - -OTTR's checks primarily focus on pull requests so you can avoid accidentally making your mistakes in your live courses. +
**WARNING**: The live content is automatically created and stored in the `docs` folder. As our writing process guide will inform you, you **should NOT make direct changes to the `docs` folder**. The automation processes will handle the preparation of these files, and you should refrain from making direct changes to them. To learn how to edit your files and write your course, please review the corresponding section in the writing process guide.
-When you submit a pull request, it triggers a sequence of automatic checks performed by GitHub Actions. These checks are designed to assist you as you add content to your course. +## About OTTR and Pull Requests + +OTTR will not completely break if you don't use pull requests, but you will be missing out on a lot of the main perks of OTTR. OTTR's checks primarily focus on pull requests so you can avoid accidentally making your mistakes in your live courses. + +When you submit a pull request on OTTR it triggers a sequence of automatic checks performed by GitHub Actions. These checks are designed to assist you as you add content to your course. These checks will: @@ -63,19 +54,19 @@ You can adjust what checks are run by editing the `config_automation.yml` file. This is further discussed in this section about [customizing GitHub Actions](./customize-robots.html). -- [Jump to OTTR Entry Level instructions](#ottr-entry-level)\ -- [Jump to OTTR Advanced instructions](#ottr-advanced) +We have two recommended ways of writing content that is based on your +comfort and interest level in using Git and GitHub. If you are already comfortable with GitHub you can skip these parts. -+
-# OTTR Entry Level {#ottr-entry-level}
+**Get started with OTTR entry level -- editing from the browser** If you are not interested in delving into GitHub, you can use this version, which is entirely conducted through the GitHub web browser.
You can edit and add content directly in the GitHub website if you prefer not to learn Git and GitHub (though we highly recommend it, as knowing how to use Git/GitHub is a useful skill to integrate into your workflow -- not just for OTTR). -## Create a new branch +**1. Create a new branch** With GitHub in order to keep your OTTR course preserved content and code is managed through the use of branches. To explain branches we'll mainly @@ -130,8 +121,7 @@ just look at the left upper corner to make sure! Now let's try making some changes. - -## Committing changes +**2. Committing changes** In your OTTR repository, on your new branch, you can now add/edit/rename currently existing files while protecting your `main` branch. Adding @@ -178,13 +168,11 @@ Then write a message about what changes you made and press the  -Now you are ready to open your pull request. +Now you are ready to open your pull request. [Jump to section titled 'Open a Pull Request'](#open-a-pull-request) -- [Jump to section titled 'Open a Pull Request'](#open-a-pull-request) - -+
**Get started with OTTR Advanced -- filing a PR from your computer**: If you are already familiar with Git and GitHub or have an interest in starting to use them, we suggest this method. It will involve some additional learning, but acquiring skills in Git and GitHub will be highly beneficial not only for OTTR but also for version control in various other contexts.
If you have an interest in utilizing GitHub (or already possess knowledge in this area), we suggest engaging with GitHub and Git beyond the GitHub website for creating your pull requests. @@ -197,7 +185,7 @@ of handling files. If you are not new to GitHub, then we recommend skipping this section and jumping to the [`Setting Up Images` section](#set-up-images). -## Cloning with Git +**1. Cloning with Git** In the GitHub workflow (excluding the Entry-Level writing method), files exist online (remote) and on your computer (local). @@ -227,8 +215,7 @@ pasting is advisable because any little typo will inhibit cloning. Now you are ready to click `Clone the repository`! It will ask you if you'd like to `Open Now`, click that. - -## Create a new branch +**2. Create a new branch** Handling branches is where you unleash the real benefit of GitHub, but it can be confusing at first. @@ -266,7 +253,7 @@ Now we can add/edit/rename currently existing files in our new branch, knowing that the content and code in the `main` branch is safe. -## Committing changes +**3. Committing changes** Adding changes to a branch is called making `commits`. To modify any files in a branch we have to first 1) Make our changes as we normally @@ -288,8 +275,7 @@ If we want to add these file changes to our current branch, we need to Great! Now the changes you've made have been added to your local branch. - -## Pushing changes +**4. Pushing changes** Note that when you've committed your changes locally (on your computer), those changes won't be on the online version of your repository. To get them to the @@ -307,9 +293,9 @@ origin in the dropdown menu and click `Submit`.  -+
**Open a pull request **
After a variable number of commits, your branch, perhaps called `a-new-branch` or any other new branch you might have made, is a @@ -341,9 +327,7 @@ banner message, where there is a button that says  -
-
-
-
- After you click on `Compare & pull request` you'll be taken to a screen where you can add information about your changes. After you are done writing your description, click `Create Pull Request`! (If you don't @@ -373,15 +355,13 @@ steps. **In summary, here are the steps involved:**  +
-Click here if you don't see the pull request message!!!
+Click here if you don't see the pull request message!!!
Note that sometimes if you have used the same branch multiple times you may need some extra steps to create a pull request. This will involve @@ -358,8 +342,6 @@ work on. Be careful that is the branch you intend.- After you click on `Compare & pull request` you'll be taken to a screen where you can add information about your changes. After you are done writing your description, click `Create Pull Request`! (If you don't @@ -373,15 +355,13 @@ steps. **In summary, here are the steps involved:**  +
- - -# Checks on the pull requests +## OTTR Checks on pull requests Once your pull request is open, the OTTR GitHub Actions checks will begin. These checks will generate reports as comments on your pull request. - +
Read these comments to begin addressing the problems with more commits
to your branch.
@@ -411,11 +391,21 @@ If you encounter situations where a spelling report or URL report doesn't look a
-
+
-# Adding new pages/chapters +### More resources for learning GitHub + +- [Using version control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) +- [Happy Git and GitHub for the useR](https://happygitwithr.com/) +- [Using Version Control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) +- [Using GitHub in a workflow in RStudio](https://hutchdatascience.org/Tools_for_Reproducible_Workflows_in_R/using-github-in-a-workflow.html) +- [GitHub for Data Scientists](https://towardsdatascience.com/introduction-to-github-for-data-scientists-2cf8b9b25fba) +- [GitHub docs about creating a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) +- [Making a Pull Request](https://www.atlassian.com/git/tutorials/making-a-pull-request) + +# Adding new chapters Adding new chapters to your OTTR course requires some specific steps in addition to what we've discussed here. @@ -477,19 +467,9 @@ navbar.
-## More resources for learning GitHub - -- [Using version control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) -- [Happy Git and GitHub for the useR](https://happygitwithr.com/) -- [Using Version Control with GitHub](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) -- [Using GitHub in a workflow in RStudio](https://hutchdatascience.org/Tools_for_Reproducible_Workflows_in_R/using-github-in-a-workflow.html) -- [GitHub for Data Scientists](https://towardsdatascience.com/introduction-to-github-for-data-scientists-2cf8b9b25fba) -- [GitHub docs about creating a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) -- [Making a Pull Request](https://www.atlassian.com/git/tutorials/making-a-pull-request) - ------------------------------------------------------------------------ -# Set up images {#set-up-images} +## Set up images {#set-up-images} To ensure consistency in style and attributions for graphics and images, and to facilitate future updates, you have the option to store all your images in a central Google Slide document. @@ -527,7 +507,7 @@ video](https://youtu.be/pNbwF263yY8) for assistance): -## Accessibility +### Accessibility Each slide and image added to the courses should be accessible so every member of your audience can use your content. @@ -545,7 +525,7 @@ There are two things to check for each slide: -## Adding images and graphics in text +### Adding images and graphics in text All images should be included in your Google Slides with the captions we discussed above. To add images in the text in your Rmd, use the @@ -583,7 +563,7 @@ of the template course for examples. -## Adding videos in text +### Adding videos in text To add a YouTube video to your Rmd files, use the following instructions: @@ -602,7 +582,7 @@ of the template course for examples. -## Adding embedded files to text +### Adding embedded files to text Occasionally, it can be beneficial to embed a website or file directly on a webpage, especially when there is a crucial link that you want learners to access without solely relying on them clicking the link.