datacarpentry/workshop-template-archived

DEPRECATED: please use https://github.com/swcarpentry/workshop-template instead

=======

This repository is the Data Carpentry template for creating websites for workshops.

1. Do not fork this repository directly on GitHub. Instead, please follow the instructions below to create a website repository for your workshop.

2. Please do your work in your repository's gh-pages branch, since that is what is automatically published as a website by GitHub.

3. Once you are done, please send your repository's URL to the Data Carpentry administrator. We build the list of workshops on the main website from the data included in your index.html page. We can only do that if you customize that page correctly and send us a link to your workshop website.

4. Please also read the notes on customizing your website and the FAQ. If you're interested in knowing more about why we do things the way we do, please check out the design notes.

5. If you are teaching Git, please create a separate repository for your learners to practice in.

6. If you run into problems, or have ideas about how to make this process simpler, please get in touch.

Creating a Repository

1. Go to GitHub's importer.

2. Click on "Check the URL". (GitHub won't import until you've done this.)

3. Select the owner for your new repository. (This will probably be you, but may instead be an organization you belong to.)

4. Choose a name for your workshop website repository. This name should have the form YYYY-MM-DD-site, e.g., 2015-07-01-yale.

5. Make sure the repository is public.

6. At this point, you should have a page like this:

   

   You can now click "Begin Import". When the process is done, you can click "Continue to repository" to visit your newly-created repository.

Note: some people have had intermittent errors during the import process, possibly because of the network timing out. If you experience a problem, please re-try; if the problem persists, please get in touch.

To clone your new repository, use:

git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-site

This is needed because the imported repository doesn't have a master branch.

Note: please do all of your work in your repository's gh-pages branch, since GitHub automatically publishes that as a website.

Customizing Your Website

1. Go into your newly-created repository, which will be at https://github.com/your_username/YYYY-MM-DD-site. For example, if your_username is gracehopper, and the site of the workshop is 'yale' the repository's URL will be https://github.com/gracehopper/2015-07-01-yale.

2. Edit index.html to customize the list of instructors, workshop venue, etc. You can do this in the browser by clicking on it in the file view and then selecting the pencil icon in the menu bar:

   

   or you can clone the repository to your desktop, edit index.html there, and push your changes back to the repository.

3. Edit _config.yml in the same way so that workshop_repo and workshop_site are the URLs of your repository and your GitHub Pages website respectively.

   Note: the URL for your website is determined automatically based on the URL for your repository. If your repository is at https://github.com/gracehopper/2015-07-01-yale, its GitHub Pages website is at http://gracehopper.github.io/2015-07-01-yale.

4. When you are done editing, you can preview your website. Again, if your repository is https://github.com/your_username/YYYY-MM-DD-site, its website will be http://your_username.github.io/YYYY-MM-DD-site.

Editing hints are embedded in index.html, and full instructions are in CUSTOMIZATION.md. This FAQ includes a few extra tips (additions are always welcome) and these notes on the background and design of this template may help as well.

Checking Your Changes

No matter how you edit index.html, you should:

1. Check your changes by running tools/check.py at the command line from the root directory of your repository.

2. Preview your changes by running tools/preview and looking at _site/index.html. To be able to preview your page locally, you must install Ruby 1.9.3 or greater plus github-pages, as described below.

For some links to work properly, particularly the link to your workshop's Eventbrite registration page, you must view _site/index.html using an HTTP server. If you have Jekyll installed, you can do this by running:

$ jekyll server -d _site

and going to http://localhost:4000.

Installing Software

In order to preview the workshop website locally on your computer, you must install the software described below.

If you aren't able to install this software (or you just can't be bothered), you can still create a website for your workshop. Every time you push a change to your website respository the live website will update automatically, so you can check your changes on the live site instead of locally.

1. Jekyll 1.0.3

   1. Check if Ruby is installed and find its version using command line:

      $  ruby -v
      

      The following commands need a minimum version of 1.9.3.

   2. Install github-pages:

      $ gem install github-pages
      

      or if that doesn't work:

      $ gem install jekyll
      $ gem install kramdown
      

      We use Kramdown to translate Markdown into HTML, instead of the default Redcarpet, because Kramdown handles Markdown inside HTML blocks.

2. The Python YAML module

   If you are using the Anaconda Python distribution, you probably already have it; if you don't, you can install it with:

   $ conda install pyyaml
   

   If you are using some other distribution, you can install the Python YAML module using Pip:

   $ pip install pyyaml
   

   and if you are on Debian Linux, you can use:

   $ apt-get install python-yaml
   

Setting Up a Separate Repository for Learners

If you are teaching Git, you should create a separate repository for learners to use in that lesson. You should not have them use the workshop website repository because:

• your workshop website repository contains many files that most learners don't need to see during the lesson, and

• you probably don't want to accidentally merge a damaging pull request from a novice Git user into your workshop's website while you are using it to teach.

You can call this repository whatever you like, and add whatever content you need to it.

Getting and Giving Help

We are committed to offering a pleasant setup experience for our learners and organizers. If you find bugs in our instructions, or would like to suggest improvements, please file an issue or mail us.

workshop-template-archived's Issues

Using the wiki for the workshops

For the workshops, we often have more information that we want to convey than is needed when the page goes 'live' for registration, information on things like the dataset or extra information that is relevant to only a given workshop. I've been trying a wiki for this type of information and liking both being able to put all the necessary info on one page or for ease of use, not having to worry about HTML or Markdown or committing to github. This is one of the ones I've used

https://github.com/datacarpentry/2015-05-03-NDIC/wiki

Wikis can be cloned like repos, so we could have a template wiki. But would that start to be too much for instructors? Should we just add places for this extra info on the main index page? Other thoughts or ideas?

Check "no quotes" instruction for humandate and humantime

Hi there

For humandate and humantime the instructions state to use a string with no quotes. The same fields in the Software Carpentry workshop-template suggest using quotes and the docstrings for check_humandate and check_humantime in tools/check.py suggest that quotes should be used.

Is this instruction correct or incorrect?

Can we update this one?

Last change was on 17 Jun 2016, more than 6 months ago. https://github.com/swcarpentry/workshop-template changed a lot during this time and has a option to use Data Carpentry logo, see https://github.com/swcarpentry/workshop-template/blob/gh-pages/index.html#L4.

Python install instructions missing

The bottom of https://github.com/datacarpentry/workshop-template/blob/gh-pages/index.html has a link to the setup instructions (https://github.com/datacarpentry/workshop-template/blob/gh-pages/index.html).

Python installation instructions are not included.

Why do only some Setup Instructions link to specific versions of software?

This can be confusing, especially for OpenRefine, where 2.5 and 2.6 live on the same page.

Add github.project_title to survey link

So that the survey link goes to the one for that workshop, in _config.yml, we should add github.project_title to the survey link, so that the information automatically gets added.

Deprecate this repository

It's my understanding that now all workshops get their template from swcarpentry/workshop-template with a variable to set to specify whether the workshop is DC, SWC or LC. Therefore I suggest this repository gets deprecated.

setup instructions in location other than workshop index.html

The setup instructions will be different for different workshops for different tools or domains, so rather than embedding them in the index.html for the workshop website, it might be good to have them on a different page.

One option might be to have a 'setup' repo in 'data carpentry' with all the installation information. Then the setup instructions will be a list of links for each OS. For instance if a workshop is spreadsheets, R and SQL, the setup instructions will be:

Windows

• link to setup/spreadsheet.html#windows
• link to setup/R.html#windows
• link to setup/SQL.html#windows

Mac

• link to setup/spreadsheet.html#mac
  etc

The advantage to this might be that we'd just have to keep the 'setup' repo updated, and each lesson that uses particular software can also link to the installation instructions from the lesson and we don't need to keep copying those pages in to different repos.

Clarification on absence of master branch

After the command showing how to clone the newly imported repository, there is this sentence

This is needed because the imported repository doesn't have a master branch.

which I find a bit unclear. If the this refers to explicitly naming the branch, I would suggest rephrasing as follows:

The -b gh-pages is needed because the imported repository doesn't have a default master branch.

I can send a PR if useful.

All lesson html pages should have link to repo

For example, this python lesson does not have a link to the python repo. This is a GitHub icon / link in the footer at the bottom of the page, but 1. that is really hidey; and 2. the link, at least for the python lesson, just goes back to the lesson, not the repo.

Perhaps the classic 'Fork me on GitHub' banner at the top right?

add checklists to template?

Could the workshop template come with the workshop checklists, with items that are check-off-able?

http://www.datacarpentry.org/checklists/

I don't think you can pre-populate issues, but maybe there could be a checklists.md file that has the checklists on it?

Clone using git rather than https

Is there a reason the imported repo is clone over https rather than over ssh with [email protected]? The latter won't ask for a username/password. Interested in a pull request?

Need to explain when you need to have Git installed locally

We should add a note at the top that if you want to work with the repo locally (such as "Check your changes" or "To clone your new repository, use: git clone -b gh-pages https://github.com/your_username/YYYY-MM-DD-site"). This is confusing for novices who don't have Git experience.

link to GitHub importer fails

Hi,

The link to the GitHub import gives a 404: file not found error.

Thanks,

Sue

Incorrect "Creating a Repository" instructions in README

Instructions tell you to:

Go to GitHub's importer.

Click on "Check the URL". (GitHub won't import until you've done this.)

When you go to the importer there is no Check the URL box to check. You have to manually paste in the clone url.

Not all data files are in the same place

The lessons page makes it seem like all the data files for the ecology lesson can be downloaded as a zip from figshare, but there is at least one in another place (on DropBox, https://www.dropbox.com/s/kbb4k00eanm19lg/Portal_rodents_19772002_scinameUUIDs.csv?dl=0).

Could we put all the data files in a single, consistent, preferably self-hosted, place? This would be particularly helpful in preparing for workshops with poor or restricted internet connectivity.

Setup Instructions: JRE a requirement for OpenRefine?

The Setup Instructions page does not explain that JRE is needed for OpenRefine.
But after communicating with a prospective student, it seems that it is indeed required, also the OpenRefine Setup Instructions do list JRE as requirement.

Installing JRE is very much dependent on the System again. Do we have any attempts to describe this to the students? In my example, it even was a 32bit system, so the first attempt failed (by trying to install 64 bit JRE).

Is this a known issue, i.e. was this a point of failure in previous DC Workshops?

Workshop title is hard-coded

The default title, "A Data Carpentry Workshop", seems to be hard-coded in _layouts/workshop.html. From memory, this wasn't the case before. I would naively expect it to be a variable in index.html. Happy to address this in a PR, just checking that it is not intentional?

Windows R install instructions refer to outdated version

Submitting this issue following an email from a learner:

Windows install instructions are as follows (from https://github.com/datacarpentry/workshop-template/blob/gh-pages/_includes/windows.html):

In the workshop, we will use RStudio. RStudio is a nice interface to the programming language R. To use RStudio, you need to install both R and RStudio.

• Download R from here
• Run the .exe file that was just downloaded
• Go to the RStudio Download page
• Under Installers select RStudio 0.98.1103 - Windows XP/Vista/7/8
• Double click the file to install it
• Once it's installed, open RStudio to make sure it works and you don't get any error messages.

The Windows option on the RStudio download page is for RStudio 1.0.143 - Windows Vista/7/8/10 .

Since I'm not an R user I don't know if the download link in the first bullet is correct.

need update to instructions for installing R on Windows

Instructions for installing R on Windows need updating.
Currently they read:

Under Installers select RStudio 0.98.1103 - Windows XP/Vista/7/8 Needs to read:

Under Installers select RStudio 0.99.903 - Windows Vista/7/8/10

There is no longer an installer that includes Win XP

index.html and check.py don't agree on country format

The comment in the index.html front matter prescribes a 2-letter lowercase country name:

country: "FIXME"      # country (lowercase two-letter ISO code such as "fr" - see https://en.wikipedia.org/wiki/ISO_3166-1)

But the check.py script expects the country to be a hyphenated full name:

COUNTRIES = [
    'Abkhazia', 'Afghanistan', 'Aland', 'Albania', 'Algeria',
    'American-Samoa', 'Andorra', 'Angola', 'Anguilla',
...
def check_country(country):
    '''"country" must be a hyphenated full country name from the list
    embedded in this script.'''

    return country in COUNTRIES

I'm happy to make the change but not sure which is preferred.