Unverified Commit 3a096698 authored by Maxim Belkin's avatar Maxim Belkin
Browse files

setup.md: add missing code block specification


Signed-off-by: default avatarMaxim Belkin <maxim.belkin@gmail.com>
parent 9057aef1
...@@ -2,30 +2,35 @@ ...@@ -2,30 +2,35 @@
title: Setup title: Setup
--- ---
Our lesson template is kept in the [`carpentries/styles` repository][styles]. The `styles` repository is carefully curated so that Our lesson template is kept in the [`carpentries/styles` repository][styles]. The `styles`
changes made to it are easily mergable by downstream lessons. The `styles` repository contains various repository is carefully curated so that changes made to it are easily mergable by downstream
bits that take Markdown files and render them as a lesson web page. For more information on how to develop lessons. The `styles` repository contains various bits that take Markdown files and render them as a
lessons and maintain them, see our [lesson-example][lesson-example]. It will walk you through the basics of lesson lesson web page. For more information on how to develop lessons and maintain them, see our
design and how to use GitHub, Markdown and Jekyll for lesson development. Follow the instructions below to make [lesson-example][lesson-example]. It will walk you through the basics of lesson design and how to
your own empty lesson in your own GitHub account. Once you've done that you can just write Markdown code and have use GitHub, Markdown and Jekyll for lesson development. Follow the instructions below to make your
lesson web pages just like the [lesson-example][lesson-example] and all of our other lessons, but with your lesson content. own empty lesson in your own GitHub account. Once you've done that you can just write Markdown code
and have lesson web pages just like the [lesson-example][lesson-example] and all of our other
Requirements: lessons, but with your lesson content.
## Requirements
* A GitHub account * A GitHub account
* A working Python 3.4+ environment to run the lesson initialization script * A working [Python 3.4+](https://www.python.org) environment to run the lesson initialization
* (Optional) A local install of [Jekyll](https://jekyllrb.com/) (version 3.2 or higher) which will require the Ruby language to be installed. script
* (Optional) A local install of [Jekyll](https://jekyllrb.com/) (version 3.2 or higher) which will
require the Ruby language to be installed.
## Creating a New Lesson ## Creating a New Lesson
We will assume that your user ID is `timtomch` and the name of your We will assume that your user ID is `timtomch` and the name of your
new lesson is `data-cleanup`. new lesson is `data-cleanup`.
1. We'll use the [GitHub's importer][importer] to make a copy of this repo in your own GitHub account. 1. We'll use the [GitHub's importer][importer] to make a copy of this repo in your own GitHub
(Note: This is like a GitHub Fork, but not connected to the upstream changes) account. (Note: This is like a GitHub Fork, but not connected to the upstream changes)
2. **Put the URL of [the styles repository][styles]** (https://github.com/carpentries/styles) in the "Your 2. Put the URL of **[the styles repository][styles]**, that is
old repository’s clone URL" box. **https://github.com/carpentries/styles** in the "Your old repository’s clone URL" box.
Do *not* use the URL of this repository, Do not use the URL of this repository,
as that will bring in a lot of example files you don't actually want. as that will bring in a lot of example files you don't actually want.
3. Select the owner for your new repository. 3. Select the owner for your new repository.
...@@ -80,6 +85,13 @@ new lesson is `data-cleanup`. ...@@ -80,6 +85,13 @@ new lesson is `data-cleanup`.
(Note that the user name above is `carpentries`, *not* `timtomch`, (Note that the user name above is `carpentries`, *not* `timtomch`,
since you are adding the master copy of the template as a remote.) since you are adding the master copy of the template as a remote.)
10. Configure the `template` remote to not download tags:
~~~
$ git config --local remote.template.tagOpt --no-tags
~~~
{: .language-bash}
10. Make sure you are using the `gh-pages` branch of the lesson template: 10. Make sure you are using the `gh-pages` branch of the lesson template:
~~~ ~~~
...@@ -98,7 +110,8 @@ new lesson is `data-cleanup`. ...@@ -98,7 +110,8 @@ new lesson is `data-cleanup`.
that cannot be put into the styles repository that cannot be put into the styles repository
(because they would trigger repeated merge conflicts). (because they would trigger repeated merge conflicts).
12. Create and edit files as explained further in [the episodes of this lesson]({{ page.root }}/#schedule). 12. Create and edit files as explained further in
[the episodes of this lesson]({{ relative_root_path }}/#schedule).
13. (requires Jekyll Setup from below) Preview the HTML pages for your lesson: 13. (requires Jekyll Setup from below) Preview the HTML pages for your lesson:
...@@ -107,13 +120,19 @@ new lesson is `data-cleanup`. ...@@ -107,13 +120,19 @@ new lesson is `data-cleanup`.
~~~ ~~~
{: .language-bash} {: .language-bash}
14. Commit your changes *and the HTML pages in the root directory of Alternatively, you can try using Docker:
your lesson repository* and push to the `gh-pages` branch of your
~~~
$ make docker-serve
~~~
{: .language-bash}
14. Commit your changes and push to the `gh-pages` branch of your
repository: repository:
~~~ ~~~
$ cd data-cleanup $ cd data-cleanup
$ git add changed-file.md changed-file.html $ git add changed-file.md
$ git commit -m "Explanatory message" $ git commit -m "Explanatory message"
$ git push origin gh-pages $ git push origin gh-pages
~~~ ~~~
...@@ -122,14 +141,13 @@ new lesson is `data-cleanup`. ...@@ -122,14 +141,13 @@ new lesson is `data-cleanup`.
15. [Tell us][email] where your lesson is so that we can add it to 15. [Tell us][email] where your lesson is so that we can add it to
the appropriate index page(s). the appropriate index page(s).
**Note:** ## Notes
1. SSH cloning (rather than the HTTPS cloning used above) 1. SSH cloning (rather than the HTTPS cloning used above)
will also work for those who have set up SSH keys with GitHub. will also work for those who have set up SSH keys with GitHub.
2. Once a lesson has been created, please submit changes 2. Once a lesson has been created, please submit changes
for review as pull requests that contain *only the modified Markdown files*. for review as pull requests that contain Markdown files only.
Do *not* submit generated HTML.
3. Some people have had intermittent errors during the import process, 3. Some people have had intermittent errors during the import process,
possibly because of the network timing out. possibly because of the network timing out.
...@@ -151,23 +169,51 @@ new lesson is `data-cleanup`. ...@@ -151,23 +169,51 @@ new lesson is `data-cleanup`.
## (Optional) Jekyll Setup for Lesson Development ## (Optional) Jekyll Setup for Lesson Development
If you want to set up Jekyll If you want to preview changes on your own machine before pushing them to GitHub,
so that you can preview changes on your own machine before pushing them to GitHub,
you must install the software described below. you must install the software described below.
(Note: Julian Thilo has written instructions for Julian Thilo wrote instructions for [installing Jekyll on Windows][jekyll-windows].
[installing Jekyll on Windows][jekyll-windows].)
1. **[Ruby](https://www.ruby-lang.org/en/downloads/)**.
1. **Ruby**. **Linux/macOS**: Ruby is usually included with Linux and macOS. However, to reliably render
This is included with Linux and macOS; lessons the way GitHub does, we have to use the same version of Ruby as GitHub. Currently,
the simplest option on Windows is to use [RubyInstaller][ruby-installer]. GitHub uses Ruby 2.5.3. In order to install Ruby 2.5.3 on Linux and macOS, we recommend using
Make sure Ruby is upto date otherwise jekyll may fail. [rbenv](https://github.com/rbenv/rbenv):
You can test your installation by running `ruby --version`.
For more information, ~~~
see [the Ruby installation guidelines][ruby-install-guide]. rbenv install 2.5.3
~~~
{: .language-bash}
And then instructing `rbenv` to use it in your lesson development process by executing the
following command from your lesson directory:
~~~
rbenv local 2.5.3
~~~
{: .language-bash}
To install `rbenv`, please use [rbenv-installer](https://github.com/rbenv/rbenv-installer).
**Windows**: Please use [RubyInstaller][ruby-installer] to install Ruby on Windows.
Upon installing Ruby, check its version by executing
~~~
ruby --version
~~~
{: .language-bash}
For more information, see [the Ruby installation guidelines][ruby-install-guide].
2. **[RubyGems][rubygems]** 2. **[RubyGems][rubygems]**
(the package manager for Ruby). is a tool which manages Ruby packages. It should be installed along with Ruby and you can
You can test your installation by running `gem --version`. test your installation by running
~~~
gem --version
~~~
{: .language-bash}
3. **[Jekyll][jekyll]**. 3. **[Jekyll][jekyll]**.
You can install this by running `gem install jekyll`. You can install this by running `gem install jekyll`.
...@@ -180,12 +226,11 @@ you must install the software described below. ...@@ -180,12 +226,11 @@ you must install the software described below.
so you will need to install these to build R lessons so you will need to install these to build R lessons
(and this example lesson). The best way to install these packages is to open an R terminal and type: (and this example lesson). The best way to install these packages is to open an R terminal and type:
``` ~~~
> install.packages('knitr', repos = 'https://', dependencies = TRUE) install.packages(c('knitr', 'stringr', 'checkpoint', 'ggplot2'),
> install.packages('stringr', repos = 'https://cran.rstudio.com', dependencies = TRUE) repos = 'https://cran.rstudio.com', dependencies = TRUE)
> install.packages('checkpoint', repos = 'https://cran.rstudio.com', dependencies = TRUE) ~~~
> install.packages('ggplot2', repos = 'https://cran.rstudio.com', dependencies = TRUE) {: .language-r}
```
If you want to run `bin/lesson_check.py` (which is invoked by `make lesson-check`) 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) you will need Jekyll (so that you have its Markdown parser, which is called Kramdown)
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment