Start using tut to improve quality of tutorials.

[jarrodu]

I am interested in converting the documentation site to use a sbt build process so that the code in the tutorials is checked at compile time. This could be done by using tut.

The documentation site started four or five years ago and is based only on jekyll. Things have progressed since then.

I don't think this would take to much effort to do. The only time consuming part would be to update the tutorials so that they pass the compiler. I suspect there will be quite a few bugs and typos in the tutorials.

This issue is partly inspired by #590 but there have been other issues and even some pull requests that could have been avoided if tut had used. For instance maybe #488 would be an example.

[soc]

Wish you the best of luck! If your proposal fails here, I'm definitely interested in looking at it over in soc/scala-lang.

[SethTisue]

the doc site (unlike scala-lang.org) is built and served by GitHub. does that have implications for whether this is feasible? before starting on the build changes, I think we'd need to plan out the delivery side.

[jarrodu]

Being served by GitHub is fine. All the work is done before GitHub even see it.

Of course I would need to do a little work on my side to do a proof of concept. I would likely push to production on a fork, ie see if GitHib can handle it, before I submit a pull request. At the moment I am certain that it will work but I have been proven wrong in the past. ;)

What do other stake holders think about the idea?

[SethTisue]

is the idea that tut would be run by Travis? I'm not that familiar with tut, does it generate output files, or is it just a testing thing that reports failures during CI, else does nothing?

[jarrodu]

I am not sure. I guess we will see. If Travis is a roadblock then we can deal with it then.

I don't think tut produces output files. It just requires that the markdown files pass a compiler before it allows the site to be generated. Given the fact that the current site is only just jekyll and markdown I am not sure why Travis is being used. I completely admit that I may be missing something important.

[SethTisue]

the reason I'm interested in involving Travis is for pull request validation. suppose someone submits a PR that changes a tutorial. if their change makes tut fail, we want to Travis to tell us that, right there on the pull request.

Travis already tells us if the changes in a pull request cause Jekyll to fail.

[SethTisue]

It just requires that the markdown files pass a compiler before it allows the site to be generated

basically I'm suggesting that instead of "before it allows the site to be generated" we do "before we allow a pull request to be merged"

if all pull requests are validated in advance by Travis, then there's no reason for tut to be in the pipeline for generating the site

[jarrodu]

From a quick look around the web it looks like it is possible to get Travis to run sbt commands. Thus the whole build process can be automated like you suggest.

tut would still be used but people writing and editing the tutorials would only need to know this if they introduce broken Scala code into the tutorials.

[soc]

@jarrodwb I think what @SethTisue is also concerned about is the impact on "built by GitHub Pages". From a perspective of a new contributor (and maintainer), it is quite nice that a PR can be merged and the website gets rebuilt automatically without any further interaction.

From my investigation, that should still work and wouldn't require running Jekyll within the sbt build, but would add some additional build step that people would need to be aware of if building locally.

While Jekyll has some nice benefits, especially combined with GitHub pages, Jekyll has also some very terrible features. I plan to revisit alternatives again in the future. Loosing the deep integration with GitHub Pages would suck, but that it doesn't support encryption is not acceptable anymore in 2016 (imho).

No encryption might not hurt that badly for documentation, but as the fork has unified the website, documentation and spec, it's a real concern for me. I really don't want people to download (native) executables over an unencrypted connection these days.

[jarrodu]

Would hosting on S3 and using SSL meet your encryption requirements? That is easy to do and can be automated like the setup we currently have.

But yeah, using PRs to build the site should not be problem.

[heathermiller]

Hi @jarrodwb thanks for your willingness to incorporate tut; it would be a huge improvement to the site! +1 to Seth's suggestion to incorporate running tut along with the Travis CI checks. Although perhaps another idea; it could be cool to somehow integrate it into the build/generation of the website as well, and display for what version of Scala the code examples compile for, generated inline with the code snippets.

However, I think to keep things focused, it's important to point out that you do not have to worry about where the documentation is hosted in your efforts to integrate tut. If you wish to integrate tut, you should only have to worry about how the build process might need to change to incorporate tut (if it needs to change and be built elsewhere from GitHub Pages). We have options for building and hosting elsewhere, but I think focusing on how tut could be integrated is the biggest unknown here.

[SethTisue]

@jarrodwb it might be helpful to look at what @larsrh is doing at typelevel/typelevel.github.com#119