Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

add bundler installation and comprehensive setup instructions #276

Merged
merged 5 commits into from Jun 26, 2020
Merged

add bundler installation and comprehensive setup instructions #276

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1e82fd5
draft more comprehensive setup instructions
fmichonneau Oct 2, 2019
5a37f5b
fix typo
fmichonneau Oct 2, 2019
f21930b
partial mac instructions
ErinBecker Oct 7, 2019
3e17b67
include @maxim-belkin and @brownsarahm comments
fmichonneau Jun 26, 2020
6f98f52
fix typo
fmichonneau Jun 26, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
239 changes: 201 additions & 38 deletions setup.md
View file
Open in desktop
Expand Up @@ -3,7 +3,7 @@ title: Setup
---

Our lesson template is kept in the [`carpentries/styles` repository][styles]. The `styles`
repository is carefully curated so that changes made to it are easily mergable by downstream
repository is carefully curated so that changes made to it are easily mergeable by downstream
lessons. The `styles` repository contains various bits that take Markdown files and render them as a
lesson web page. For more information on how to develop lessons and maintain them, see our
[lesson-example][lesson-example]. It will walk you through the basics of lesson design and how to
Expand Down Expand Up @@ -174,73 +174,236 @@ before pushing them to GitHub.

In order to preview changes locally, you must install the software described below.

1. **[Ruby](https://www.ruby-lang.org/en/downloads/)**.
### Windows

fmichonneau marked this conversation as resolved.
Show resolved Hide resolved
For Windows, there are two main ways to setup your system to be able to render the lessons.

- Option 1 relies on the Windows Subsystem for Linux (WSL). WSL allows you to run a Linux
environment directly from Windows.
- Option 2 relies on using Windows built-in applications.

> ## Option 1 - Using the Windows Subsystem for Linux (WSL)
>
> If your version of Windows supports it, using the WSL will make the installation of the tools
> needed easier. Instructions to install Linux distributions from Windows 10/Windows Server are
> available from the [Microsoft website](https://docs.microsoft.com/en-us/windows/wsl/about).
>
> Once you have installed a Linux distribution, you can follow the installation instructions for
> [Linux](#linux-ubuntu) listed below. If you install a distribution other than Ubuntu, you will
> need to adjust the commands that install the packages.
{: .solution}

> ## Option 2 - Using Windows built-in applications
>
> With the instructions below, you'll be able to preview websites for non-R based lessons. You'll be
> able to do so from the Git Bash terminal or from the "Command Prompt with Ruby" that comes with
> the Ruby installation. You won't be able to use the `make` commands as Make isn't available from
> the Git Bash terminal (see the optional section below for more info).
>
> 1. **Ruby**, go to <https://rubyinstaller.org/> choose Ruby+DevKit for your
> system (typically x64), and the most recent version available. During the
> installation process, choose to install the MSYS2 toolchain. On the last step
> of the installation screen, make sure that "Run 'ridk install'" is checked.
> This will bring a terminal window with 3 options, press "Enter" (for the
> default installation). After this step completes, you'll be prompted again,
> and press "Enter" again (for the default option). Once the installation is
> complete, restart your system.
>
>2. Navigate to the folder that contains the lesson, and you can now use `bundle
> exec jekyll serve` from your Git Bash terminal to preview the lessons.
>
> ### Optional (but recommended)
>
> With these instructions, you'll be able to use the `make` commands and render all lessons
> including those that use R. However, you won't be able to do so from the Git Bash terminal, but
> from the other terminals (Windows Powershell, cmd.exe, or the Command Prompt with Ruby).
>
>1. In the File Explorer, right-click on "This PC" icon, and click on
> "Properties". Click on "Advanced System Settings", and click on the button
> "Environment Variables". Click on the variable "Path", and then the "Edit"
> button. Click on the "New" button and add `C:\Ruby26-x64\msys64\usr\bin` (use
> the File Explorer to make sure this is the correct path for your Ruby and
> MSYS2 installation). If you're working on R-based lessons and R isn't already
> listed there, you need to add it by adding `C:\Program Files\R\R-3.x.x\bin`
> (using the correct path and R version number for your installation).
>
>2. Open the "Command Prompt with Ruby" (if it was open before you edited the
> Path, close it and re-open it).
{: .solution}

Regardless of the option you chose, go to the section [For Everyone](#for-everyone).

### macOS

1. First make sure you have Homebrew installed by doing
fmichonneau marked this conversation as resolved.
Show resolved Hide resolved

To install Homebrew, open the [Homebrew website](https://brew.sh/) and copy/paste the first command
on that page into your Terminal. It will look something like:

~~~
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
~~~
{: .language-bash}

If you're not sure whether you have brew installed, type

~~~
brew help
~~~
{: .language-bash}

If you have Homebrew installed, you should see something like:

~~~
Example usage:
brew search [TEXT|/REGEX/]
brew info [FORMULA...]
brew install FORMULA...
brew update
brew upgrade [FORMULA...]
brew uninstall FORMULA...
brew list [FORMULA...]

Troubleshooting:
brew config
brew doctor
brew install --verbose --debug FORMULA

Contributing:
brew create [URL [--no-fetch]]
brew edit [FORMULA...]

Further help:
brew commands
brew help [COMMAND]
man brew
https://docs.brew.sh
~~~
{: .output}


2. **Ruby** -- `brew install ruby`

3. **bundler** -- `gem install bundler --user-install`

4. Go to the section [For Everyone](#for-everyone)

### Linux (Ubuntu)

1. **[Ruby](https://www.ruby-lang.org/en/downloads/)** and other dependencies.

You will need to have the following packages installed (some might already
be on your system):

**Linux/macOS**: Ruby is usually included with Linux and macOS ---
this is usually sufficient to preview your changes locally.
~~~
sudo apt-get install ruby ruby-dev build-essential libxml2-dev
~~~
{: .language-bash}

If you aren't able to preview reliably with your default Ruby installation,
you can use the same version of Ruby as GitHub. Currently,
GitHub uses Ruby 2.5.3. In order to install Ruby 2.5.3 on Linux and macOS, we recommend using
[rbenv](https://github.com/rbenv/rbenv):
2. **[bundler](https://bundler.io/)**

~~~
rbenv install 2.5.3
gem install bundler --user-install
~~~
{: .language-bash}

And then instructing `rbenv` to use it in your lesson development process by executing the
following command from your lesson directory:
`gem` is the package management framework for Ruby. It was installed as part
of Ruby in the step above. `bundler` is also a package manager but at the
scale of a project instead of being system-wide. It makes it easier to
manage dependencies.


### For Everyone

1. **The GitHub Pages Ruby Gem**

Make sure there is a `Gemfile` at the root of your lesson repository. This
file should only contain:

~~~
rbenv local 2.5.3
source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
~~~

If you don't have it, create it and the two lines above to it.
brownsarahm marked this conversation as resolved.
Show resolved Hide resolved

At the root of your repository type

~~~
bundle update
~~~
{: .language-bash}

To install `rbenv`, please use [rbenv-installer](https://github.com/rbenv/rbenv-installer).
If you haven't used `bundler` yet for your project, this command will
install all the needed dependencies. Otherwise, it will update them to match
the current versions used by GitHub Pages.
brownsarahm marked this conversation as resolved.
Show resolved Hide resolved

**Windows**: Please use [RubyInstaller][ruby-installer] to install Ruby on Windows.
4. **Generate the lesson**

Upon installing Ruby, check its version by executing
Now you are ready to run jekyll to build your website and run a local server. To do this run:

~~~
ruby --version
make serve
~~~
{: .language-bash}

Windows users should select the start menu option `Start command prompt with Ruby`
to execute the above command.
There will be several lines of output after this. If there were errors or warnings you can use
them to fix your lesson and run again if ti it failed. If it was successful the last few lines
will include `Server address: http://217.0.0.1:4000` and `Server running... press ctrl-c to
stop`. You can see your rendered site by pointing your browser to the address shown.

For more information, see [the Ruby installation guidelines][ruby-install-guide].
### For R-based lessons

2. **[RubyGems][rubygems]**
is a tool which manages Ruby packages. It should have been installed along with Ruby and you can
test your installation by running
You will need a recent version of R (>= 3.5.0). Installation instructions are available from the [CRAN website](https://cran.r-project.org).

We use the [knitr][cran-knitr], and [remotes](https://cran.r-project.org/package=remotes) to format
lessons written in R Markdown and figure out needed packages to execute the code in the lesson. You
will need to install the `remotes` package to build R lessons (and this example lesson), the other
packages will be installed automatically during the rendering of the lesson. You can install this
package by opening an R terminal and typing:

~~~
install.packages('remotes', repos = 'https://cran.rstudio.com')
~~~
{: .language-r}

### Troubleshooting

1. Check your version of Ruby:

~~~
ruby -v
~~~
{: .language-bash}

You need Ruby 2.1.0 or later (currently GitHub pages uses Ruby 2.5.3). If you
have an older version of Ruby, if possible upgrade your operating system to a
more recent version. If it's not possible, consider using [rbenv](https://github.com/rbenv/rbenv).

~~~
gem --version
rbenv install 2.5.3
~~~
{: .language-bash}

3. **[Jekyll][jekyll]**.
You can install this by running `gem install jekyll`.
On macOS, a user does not have a permission to write to `/Library/Ruby/Gems/`.
Run `gem install jekyll --user-install` instead.
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}

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). The best way to install these packages is to open an R terminal and type:
2. **[RubyGems][rubygems]**
is a tool which manages Ruby packages. It should have been installed along with Ruby and you can
test your installation by running

~~~
install.packages(c('knitr', 'stringr', 'checkpoint', 'ggplot2'),
repos = 'https://cran.rstudio.com', dependencies = TRUE)
gem --version
~~~
{: .language-r}
{: .language-bash}

3. If you want to run `bin/lesson_check.py` (which is invoked by `make lesson-check`)
fmichonneau marked this conversation as resolved.
Show resolved Hide resolved
you will need the [PyYAML][pyyaml] module for Python 3.

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)
and the [PyYAML][pyyaml] module for Python 3.

{% include links.md %}