Add a single-page (printable) version of the Scala Style Guide

[kswmsw]

The Scala Style Guide is an important document. At the moment it appears on many separate pages, which is great for browsing but not so good for printing out or for reading right through. It would be great if there was a single-page version available for these purposes.

I'm very happy to do the work necessary to make this happen, but I'm not sure where to start. Please can someone point me at the code that generates HTML from the .md pages in /style?

Thanks.

--KW 8-)

[heathermiller]

Hi @kswmsw, thanks a lot for volunteering to help! We'd love it if there was a PDF generated from the Scala Style Guide. The HTML source for the website is generated using Jekyll. Jekyll is a command-line tool that converts markdown into static HTML. Actually, docs.scala-lang.org is hosted by Github, Github also runs Jekyll on the server-side for us.

I'm no expert in generating PDF from markdown sources, though a promising tool looks to be PrinceXML. It generates PDFs from HTML. I imagine we could always install some kind of post-commit hook to trigger the PrinceXML build of the PDF from generated HTML (we could move docs.scala-lang.org to our own servers) if this PrinceXML approach seems to be a viable solution.

That's at least one lead. There could be other options too :)

[kswmsw]

Thanks Heather! That's the info I need - I'll take a look and see what I can find, and keep you posted.

[heathermiller]

No problem! Thanks for stepping up to help! Looking forward :)

[kswmsw]

Hi Heather - just to let you know I haven't forgotten this! I hope to make some progress soon (I've been very busy with other things in the last month).

[heathermiller]

No worries – just keep us updated, let us know if you run into any trouble.

[nathanclayton]

I've been taking a swing at getting it into a PDF format - the cheatsheet is already up. You can check out the progress at RTD or the Bitbucket. Currently the style guide starts at Page 11 in the auto-generated PDF.

[kw217]

Great stuff, thanks! I got pulled away onto other things and never got started on this, so thanks for taking it up.

[nathanclayton]

I've completed adding the Style Guide to the Sphinx documentation. It starts at page 19 currently in the PDF format, however since the table of contents is linked to the correct page you should always be able to get to it without issue.

[soc]

Single page, printing preview looks fine, too: http://get-scala.org/documentation/styleguide/

[heathermiller]

Not really:

Also, the "responsive" version is more difficult to read IMO than the non-responsive version (it doesn't scroll horizontally so as to read cut off text, so, it's impossible to read):

[soc]

Thanks! This is weird, I'll investigate and fix it.

[SethTisue]

not sure if #606 will make this any easier/better