Skip to content
setup.md 6.01 KiB
Newer Older
Greg Wilson's avatar
Greg Wilson committed
---
layout: page
title: Setup
permalink: /setup/
---
## Setup Instructions for Actual Lessons

Greg Wilson's avatar
Greg Wilson committed
1.  Installation instructions for core lessons are included in the [workshop template's home page][template],
    so that they are all in one place.
    The `setup.md` files of core lessons link to
    the appropriate sections of the [workshop template page][{{ site.workshop_repo }}].
Greg Wilson's avatar
Greg Wilson committed
2.  Other lessons' `setup.md` include full installation instructions organized by OS
    (following the model of the workshop template home page).
## Setting Up for Lesson Development
Greg Wilson's avatar
Greg Wilson committed

If you want to set up Jekyll
so that you can preview changes on your own machine before pushing them to GitHub,
Greg Wilson's avatar
Greg Wilson committed
you must install the software described below.
Greg Wilson's avatar
Greg Wilson committed
(Note: Julian Thilo has written instructions for
[installing Jekyll on Windows][jekyll-windows].)
Greg Wilson's avatar
Greg Wilson committed

Greg Wilson's avatar
Greg Wilson committed
1.  **Ruby**.
Greg Wilson's avatar
Greg Wilson committed
    This is included with Linux and Mac OS X;
Greg Wilson's avatar
Greg Wilson committed
    the simplest option on Windows is to use [RubyInstaller][ruby-installer].
Greg Wilson's avatar
Greg Wilson committed
    You can test your installation by running `ruby --version`.
    For more information,
Greg Wilson's avatar
Greg Wilson committed
    see [the Ruby installation guidelines][ruby-install-guide].
Greg Wilson's avatar
Greg Wilson committed

Greg Wilson's avatar
Greg Wilson committed
2.  **[RubyGems][rubygems]**
Greg Wilson's avatar
Greg Wilson committed
    (the package manager for Ruby).
    You can test your installation by running `gem --version`.

Greg Wilson's avatar
Greg Wilson committed
3.  **[Jekyll][jekyll]**.
Greg Wilson's avatar
Greg Wilson committed
    You can install this by running `gem install jekyll`.
Greg Wilson's avatar
Greg Wilson committed

4.  **R Packages**.
    We use [knitr][cran-knitr], [stringr][cran-stringr], and [checkpoint][cran-checkpoint]
    to format lessons written in R Markdown,
    so you will need to install these to build R lessons
    (and this example lesson).

Greg Wilson's avatar
Greg Wilson committed
If you want to run `bin/lesson_check.py` (which is invoked by `make lesson-check`)
you will need Jekyll (so that you have its Markdown parser, which is called Kramdown)
Greg Wilson's avatar
Greg Wilson committed
and the [PyYAML][pyyaml] module for Python 3.
Greg Wilson's avatar
Greg Wilson committed

## Creating a New Lesson

We will assume that your user ID is `gvwilson` and the name of your
lesson is `data-cleanup`.

1.  Go to [GitHub's importer][importer].

2.  Put the URL of [the styles repository][styles] in the "Your old repository’s clone URL" box.
    Do *not* use the URL of this repository,
    as that will bring in a lot of example files you don't actually want.

3.  Select the owner for your new repository.
    In our example this is `timtomch`,
Greg Wilson's avatar
Greg Wilson committed
    but it may instead be an organization you belong to.

4.  Choose a name for your lesson repository.
Greg Wilson's avatar
Greg Wilson committed
    In our example, this is `data-cleanup`.

5.  Make sure the repository is public.
6.  At this point, you should have a page like this:
    ![]({{ page.root }}/fig/using-github-import.png)
Greg Wilson's avatar
Greg Wilson committed

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

7.  Clone your newly-created repository to your desktop:
    $ git clone -b gh-pages https://github.com/timtomch/data-cleanup.git
Greg Wilson's avatar
Greg Wilson committed
    ~~~
Greg Wilson's avatar
Greg Wilson committed
    {: .source}
Greg Wilson's avatar
Greg Wilson committed

    Note that the URL for your lesson will be different than the one above.

8.  Go into that directory using:
Greg Wilson's avatar
Greg Wilson committed

    ~~~
    $ cd data-cleanup
    ~~~
Greg Wilson's avatar
Greg Wilson committed
    {: .source}
Greg Wilson's avatar
Greg Wilson committed

    Note that the name of your directory will be different,
    since your lesson probably won't be called `data-cleanup`.

9. Manually add the styles repository as a remote called `template`:
Greg Wilson's avatar
Greg Wilson committed

    ~~~
    $ git remote add template https://github.com/swcarpentry/styles.git
    ~~~
Greg Wilson's avatar
Greg Wilson committed
    {: .source}
Greg Wilson's avatar
Greg Wilson committed

    This will allow you to pull in changes made to the template,
    such as improvements to our CSS style files.
    (Note that the user name above is `swcarpentry`, *not* `timtomch`,
Greg Wilson's avatar
Greg Wilson committed
    since you are adding the master copy of the template as a remote.)

10. Make sure you are using the `gh-pages` branch of the lesson template:

    ~~~
    $ git checkout gh-pages
    ~~~
    {: .source}

	This will ensure that you are using the most "stable" version of the
	template repository. Since it's being actively maintained by the
	Software Carpentry community, you could end up using a development branch
	that contains experimental (and potentially not working) features without
	necessarily realising it. Switching to the `gh-branch` ensures you are
	using the "stable" version of the template.

11. Run `bin/lesson_initialize.py` to create all of the boilerplate files
Greg Wilson's avatar
Greg Wilson committed
    that cannot be put into the styles repository
    (because they would trigger repeated merge conflicts).

12. Create and edit files as explained in [the episodes of this lesson]({{ page.root }}/#schedule).
Greg Wilson's avatar
Greg Wilson committed

13. Preview the HTML pages for your lesson:

    ~~~
    $ make serve
    ~~~
Greg Wilson's avatar
Greg Wilson committed
    {: .source}
Greg Wilson's avatar
Greg Wilson committed

14. Commit your changes *and the HTML pages in the root directory of
    your lesson repository* and push to the `gh-pages` branch of your
    repository:

    ~~~
    $ cd data-cleanup
    $ git add changed-file.md changed-file.html
    $ git commit -m "Explanatory message"
    $ git push origin gh-pages
    ~~~
Greg Wilson's avatar
Greg Wilson committed
    {: .source}
Greg Wilson's avatar
Greg Wilson committed

15. [Tell us][contact] where your lesson is so that we can add it to
    the appropriate index page(s).

**Note:**

1.  SSH cloning (rather than the HTTPS cloning used above)
    will also work for those who have set up SSH keys with GitHub.

2.  Once a lesson has been created, please submit changes
    for review as pull requests that contain *only the modified Markdown files*.
    Do *not* submit generated HTML.

3.  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][contact].

[cran-checkpoint]: https://cran.r-project.org/web/packages/checkpoint/index.html
Greg Wilson's avatar
Greg Wilson committed
[contact]: mailto:lessons@software-carpentry.org
[importer]: http://import.github.com/new
Greg Wilson's avatar
Greg Wilson committed
[jekyll-windows]: http://jekyll-windows.juthilo.com/
[jekyll]: https://jekyllrb.com/
[cran-knitr]: https://cran.r-project.org/web/packages/knitr/index.html
Greg Wilson's avatar
Greg Wilson committed
[pyyaml]: https://pypi.python.org/pypi/PyYAML
[ruby-install-guide]: https://www.ruby-lang.org/en/downloads/
[ruby-installer]: http://rubyinstaller.org/
[rubygems]: https://rubygems.org/pages/download/
[cran-stringr]: https://cran.r-project.org/web/packages/stringr/index.html
Greg Wilson's avatar
Greg Wilson committed
[styles]: https://github.com/swcarpentry/styles/