Upgraded project docs to include incremental switch

[charafau]

After discussion with @SethTisue (here: scala/scala-lang#493 ) about compilation speed I have upgraded jekyll to 3.3.0
and upgraded docs to include -I incremental compilation flag.

At first it took ~5 minutes on my machine to build the whole thing but after that only few seconds:

Incremental build: enabled
      Generating...
                    done in 2.065 seconds.

Hope it helps with further updates.

Here's the list of used gems:

➜  scala.github.com git:(feat/jekyll_incremental_upgrade) bundle show
Gems included by the bundle:
  * addressable (2.4.0)
  * bundler (1.13.5)
  * colorator (1.1.0)
  * ffi (1.9.14)
  * forwardable-extended (2.6.0)
  * jekyll (3.3.0)
  * jekyll-redirect-from (0.11.0)
  * jekyll-sass-converter (1.4.0)
  * jekyll-watch (1.5.0)
  * kramdown (1.12.0)
  * liquid (3.0.6)
  * listen (3.0.8)
  * mercenary (0.3.6)
  * pathutil (0.14.0)
  * rb-fsevent (0.9.7)
  * rb-inotify (0.9.7)
  * rouge (1.11.1)
  * safe_yaml (1.0.4)
  * sass (3.4.22)

For more speed improvements we would probably need to move to hugo or some other static generator.

[jarrodu]

Can we keep the dependency on github-pages. This makes it easy to assure ourselves that the site will look the same in production as it does on our personal computers.

[charafau]

Sure, no problem

[jarrodu]

Incremental compilation worded just fine for me with the prior Gemfile. Is there another reason for the upgrade?

[charafau]

I thought that there is no specified version of Jekyll which is used. Some people were probably using 3.x (that's why incremental compilation worked) but majority of people don't know what version is used in production

[jarrodu]

Take a look at the Gamefile.lock file. Jekyll 3.0.3 is being used.

I should take a look at our documentation and see if it describes how to get local development setup properly. I am away from my computer at the moment.

[jarrodu]

Are you using bundle exec jekyll ...? The dependencies referenced in the README links to the Jekyll site. This should be change to the bundler site. jekyll ... commands should not be used without Bundler.

If Bundler is used then everyone will be using the Jekyll version listed in the Gemfile.lock file.

[charafau]

Hello @jarrodwb I'm using bundle exec jekyll serve -I --watch command. We can stay with jekyll 3.0.3 but I would like to add it to Gemfile and upgrade docs for incremental compilation. What do you think ?

[soc]

As suggested, posting this publicly...
I'm not sure it's doing the right thing. The gh-pages gem is used because Github promises that this gets you exactly the versions they use when building the site.
So I would suggest not getting rid of it, even if newer versions fix bugs, it will be more confusing because the bugs will be gone locally, but still exist on the published website until GitHub also updates their stack.

[charafau]

Thank you. I understood issue. I will revert gem changes and add only -I switch into readme.

[jarrodu]

I suggest keeping the changes to the README but being rid of the other changes. The current Gemfile does exactly what we need.

If we want to update the site dependences we can do that in a different PR. All that needs to be done is a 'bundle update' then commit the new Gemfile.lock file. This should update Jekyll to about 3.2.x something.

I really think that gh pages gem should control the version of Jekyll. Of course if we move the site then we can do something different.

Thanks for the changes to the README. 😀

On another note. Nice to see you Simon!

[SethTisue]

according to https://pages.github.com/versions/, GitHub Pages is on Jekyll 3.2.1. so isn't that the version our Gemfile should have as well...?

[jarrodu]

See my last comment. If we want to update site dependences then we should use bundle update.

https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/#keeping-your-site-up-to-date-with-the-github-pages-gem

Hard coding the version number is s mistake. If you want to update Jekyll then we can summit another PR. It really does not have much to do with this thread.

[SethTisue]

All that needs to be done is a 'bundle update' then commit the new Gemfile.lock file. This should update Jekyll to about 3.2.x something.

sorry, I was skimming and missed this.

I tried it just now and bundle install succeeded, but Gemfile.lock didn't change.

I think we need to make this change in Gemfile:

-    github-pages (46)
+    github-pages (98)

and then run bundle install. which I tried but I got errors I didn't understand (Gem::Ext::BuildError: ERROR: Failed to build gem native extension)

I don't understand the difference between bundle install and bundle update... but anyway... bumping the github-pages version number is the right thing to do, isn't it?

[jarrodu]

I don't think the gemfile should be changed at all.

If you want to use bundle install then you need to delete the gemfile.lock file first. If you use the bundle update then you don't need to delete it. It should be changed by the update command.

The whole point of the lock file is that all the developers use the same versions of all gem dependences.

The bundle install command will install all the versions in the lock file. Also the lock file should not be edited by hand.

Your error, I think, comes from not having system dependencies. Those dependencies would be managed elsewhere, outside of the gems. Maybe some like a C library.

[SethTisue]

I don't think the gemfile should be changed at all

Why is it good to have an old version of github-pages listed in the Gemfile, instead of the current version that GitHub Pages actually uses?

Why is it good to have a version of jekyll listed in the Gemfile that doesn't match GitHub either?

[jarrodu]

I will try to explain this again when I get home in about two hours.

[jarrodu]

Okay @SethTisue I am back. I will make a pull request to update the dependencies and I will go through all of the steps to explain how it is done.

Feel free to find me in gitter if you want to chat before I get the other PR finished.

[jarrodu]

See #601 for a bit on updating dependencies.

@SethTisue I think your error you mentioned earlier is either from the ffi gem or the nokogiri gem. You are missing a system dependency somewhere. You should be able to figure out which one by looking at those two gems. I would start with nokogiri. It's name sounds familiar and I think I ran into a similar problem on Ubuntu a while ago.

[charafau]

I reverted changes for gems, just upgraded docs. Should be fine now.

[SethTisue]

Are the backquotes in this line supposed to be there?

[charafau]

I added it as indication for users, that first build might take a while. I can change it if you think it's not a good idea.

[SethTisue]

I don't have a strong feeling about it. I'll go ahead and merge.

The fact that it takes so long now has its own ticket: #607

[SethTisue]

LGTM other than the one nit

[SethTisue]

thanks @charafau and @jarrodwb!