Tweet
Tweet

Slide 1

Slide 1 text

Guillaume Laforge 
 @glaforge Behind the new Groovy website

Slide 2

Slide 2 text

Guillaume Laforge Groovy project lead @glaforge http://glaforge.appspot.com

Slide 3

Slide 3 text

Cédric Champeau Groovy core developer @cedricchampeau http://melix.github.io/blog/

Slide 4

Slide 4 text

Cédric Champeau Groovy core developer @cedricchampeau http://melix.github.io/blog/

Slide 5

Slide 5 text

Documentation

Slide 6

Slide 6 text

Before

Slide 7

Slide 7 text

No content

Slide 8

Slide 8 text

No content

Slide 9

Slide 9 text

After

Slide 10

Slide 10 text

After

Slide 11

Slide 11 text

After

Slide 12

Slide 12 text

After

Slide 13

Slide 13 text

After

Slide 14

Slide 14 text

@glaforge New documentation goals • One documentation version per release • Integrated in the build process • Should be easy to write • Should be tested 10

Slide 15

Slide 15 text

Executable documentation

Slide 16

Slide 16 text

@glaforge How? Asciidoctor to the rescue! • Markup based documentation engine • Derived from Asciidoc • Lightweight syntax • Feature rich • Highly customizable 12

Slide 17

Slide 17 text

@glaforge How? Asciidoctor to the rescue! 13 = Syntax
 
 This chapter covers the syntax of the Groovy programming language.
 The grammar of the language derives from the Java grammar,
 but enhances it with specific constructs for Groovy, and allows certain simplifications.
 
 == Comments
 
 === Single line comment
 
 Single line comments start with `//` and can be found at any position in the line.
 The characters following `//`, till the end of the line, are considered part of the comment.

Slide 18

Slide 18 text

@glaforge Directory structure 14 src/spec/ assets doc test test-resources

Slide 19

Slide 19 text

@glaforge Directory structure 14 src/spec/ assets doc test test-resources images, css, javascript…

Slide 20

Slide 20 text

@glaforge Directory structure 14 src/spec/ assets doc test test-resources images, css, javascript… asciidoctor source files

Slide 21

Slide 21 text

@glaforge Directory structure 14 src/spec/ assets doc test test-resources images, css, javascript… asciidoctor source files documentation specific tests

Slide 22

Slide 22 text

@glaforge Directory structure 14 src/spec/ assets doc test test-resources images, css, javascript… asciidoctor source files documentation specific tests test sources

Slide 23

Slide 23 text

Every single snippet of code you see in the documentation is tested

Slide 24

Slide 24 text

OMG! Executable documentation!

Slide 25

Slide 25 text

@glaforge Including external snippets of code 17 [source,groovy]
 ----
 include::src/spec/test/SyntaxTest.groovy[tags=single_line_comment,indent=0]
 ----

Slide 26

Slide 26 text

@glaforge Including external snippets of code 17 [source,groovy]
 ----
 include::src/spec/test/SyntaxTest.groovy[tags=single_line_comment,indent=0]
 ---- Groovy syntax highlighting for the block of code

Slide 27

Slide 27 text

@glaforge Including external snippets of code 17 [source,groovy]
 ----
 include::src/spec/test/SyntaxTest.groovy[tags=single_line_comment,indent=0]
 ---- Groovy syntax highlighting for the block of code include directive

Slide 28

Slide 28 text

@glaforge Including external snippets of code 17 [source,groovy]
 ----
 include::src/spec/test/SyntaxTest.groovy[tags=single_line_comment,indent=0]
 ---- Groovy syntax highlighting for the block of code include directive source file to include

Slide 29

Slide 29 text

@glaforge Including external snippets of code 17 [source,groovy]
 ----
 include::src/spec/test/SyntaxTest.groovy[tags=single_line_comment,indent=0]
 ---- Groovy syntax highlighting for the block of code include directive source file to include just include a portion

Slide 30

Slide 30 text

@glaforge Snippet demarcation 18 void testSingleLineComment() {
 // tag::single_line_comment[]
 // a standalone single line comment
 println "hello" // a comment till the end of the line
 // end::single_line_comment[]
 }

Slide 31

Slide 31 text

@glaforge Snippet demarcation 18 void testSingleLineComment() {
 // tag::single_line_comment[]
 // a standalone single line comment
 println "hello" // a comment till the end of the line
 // end::single_line_comment[]
 } tag::tag_name[] end::tag_name[]

Slide 32

Slide 32 text

@glaforge Narrative 19 They can be seen as *interfaces* carrying both *default implementations* and *state*. A trait is defined using the `trait` keyword:
 
 [source,groovy]
 ----
 include::src/spec/test/TraitsSpecTest.groovy[tags=flying_simple,indent=0]
 ----
 <1> declaration of a trait
 <2> declaration of a method inside a trait

Slide 33

Slide 33 text

@glaforge Callouts 20 class TraitsSpecTest extends GroovyTestCase {
 void testTraitDeclaration() {
 assertScript ''' // tag::flying_simple[]
 trait FlyingAbility { // <1>
 String fly() { "I'm flying!" } // <2>
 }
 // end::flying_simple[]
 
 // tag::bird[]
 class Bird implements FlyingAbility {} // <1>
 def b = new Bird() // <2>
 assert b.fly() == "I'm flying!" // <3>
 // end::bird[]
 '''
 }

Slide 34

Slide 34 text

@glaforge Narrative and callouts rendered 21

Slide 35

Slide 35 text

@glaforge Gradle 22 apply plugin: 'org.asciidoctor.gradle.asciidoctor'
 
 asciidoctor {
 def (full, major, minor, patch, flavor) = (groovyVersion =~ /(\d+)\.(\d++)\.(\d+)(?:-(.+))?/)[0]
 logDocuments = true
 sourceDir = project.file('src/spec/doc')
 options = [
 attributes: [
 'rootProjectDir': rootProject.projectDir,
 'source-highlighter': 'prettify',
 groovyversion: groovyVersion,
 'groovy-major-version': major,
 'groovy-minor-version': minor,
 'groovy-patch-version': patch,
 'groovy-full-version': groovyVersion,
 'groovy-short-version': "${major}.${minor}",
 doctype: 'book',
 revnumber: groovyVersion,
 icons: 'font',
 toc2: '',
 specfolder: 'src/spec/doc',
 linkcss: '',
 stylesheet: "assets/css/style.css",
 encoding: 'utf-8',
 toclevels: 10,
 numbered: ''
 ]
 ]
 }

Slide 36

Slide 36 text

@glaforge In summary • Documentation rewritten from scratch – help still needed to fill the many gaps though! • Narrative written using Asciidoctor • Code must belong to test cases • Makes guarantees that doc is up-to-date • Integrated through Gradle 23

Slide 37

Slide 37 text

Website

Slide 38

Slide 38 text

After…

Slide 39

Slide 39 text

After…

Slide 40

Slide 40 text

After…

Slide 41

Slide 41 text

After…

Slide 42

Slide 42 text

After…

Slide 43

Slide 43 text

@glaforge Objectives • Facelifting and responsiveness • Easy maintenance / hosting • Well organized • Make contributions easy • Eat your own dog food 26

Slide 44

Slide 44 text

@glaforge Responsiveness 27

Slide 45

Slide 45 text

@glaforge Responsiveness 27 Drop-down menu

Slide 46

Slide 46 text

@glaforge Responsiveness 27 Drop-down menu Readable from any modern browsers, both desktop and mobile

Slide 47

Slide 47 text

@glaforge Responsiveness 27 Drop-down menu Lead to Github’s online editor! Readable from any modern browsers, both desktop and mobile

Slide 48

Slide 48 text

@glaforge Technical solution • Bootstrap theme by Damien Vitrac • Fully static • Uses a Groovy DSL for contents • Forkable on GitHub • Uses the Markup Template Engine • Baked with Gradle 28

Slide 49

Slide 49 text

@glaforge Markup template engine • Introduced in Groovy 2.3 • Fully fledged template engine • Primarily aimed at generating markup contents • Templates look like Groovy builders • Statically compiled templates • Optional type checking 29

Slide 50

Slide 50 text

@glaforge Markup template engine • No more closing tag nightmare • Can be very fast once templates are compiled • Support for i18n • Used in both Spring Boot and Ratpack 30

Slide 51

Slide 51 text

@glaforge A basic template 31 downloads.each { dl -> div(class:'download') {
 a(href:dl.url, "Groovy $dl.version") }
 }

Slide 52

Slide 52 text

@glaforge Template rendered 32

 Groovy 2.3.8




 Groovy 2.3.9


Slide 53

Slide 53 text

@glaforge Includes 33 include template: 'other_template.tpl'
 include unescaped: 'raw.txt'
 include escaped: 'to_be_escaped.txt'

Slide 54

Slide 54 text

@glaforge Layouts 34 layout 'layouts/main.groovy', true,
 pageTitle: 'The Groovy programming language',
 mainContent: contents {
 div(id: 'content') {
 include unescaped: 'html/index.html'
 
 section(class: "row colset-3-article") {
 h1 { strong "Groovy events you shouldn't miss!" }
 allEvents.keySet().take(3).each { String eventName ->
 Event event = allEvents[eventName]
 article {
 div(class: 'content') {
 …

Slide 55

Slide 55 text

@glaforge Layout 35 layout 'layouts/page.groovy', true,
 mainContent: contents {
 // 'Content'
 div {
 include template: 'includes/topmenu.groovy'
 
 // main contents goes here!
 mainContent() 
 include template: 'includes/bottommenu.groovy'
 }
 }

Slide 56

Slide 56 text

Starting the engine

Slide 57

Slide 57 text

@glaforge Setting up the engine 37 def tplConf = new TemplateConfiguration( autoIndent : true, autoNewLine: true ) 
 def classLoader = … 
 tplEngine = new MarkupTemplateEngine(
 classLoader, tplConf,
 new CachingTemplateResolver())

Slide 58

Slide 58 text

@glaforge Template resolver • Allows… – custom template resolution/loading – overriding i18n behavior – custom caching strategies 38

Slide 59

Slide 59 text

@glaforge Rendering 39 tplEngine.createTemplateByPath("pages/${page}.groovy")
 .make(model)

Slide 60

Slide 60 text

@glaforge Markup template engine • Even if a template contains unresolved variables – Statically compiled – Uses type checking extensions under the hood – Allows optional type checking of model – Even faster if type checked 40

Slide 61

Slide 61 text

@glaforge Type checked models 41 modelTypes = { List pages } 
 pages.each { page -> p("Page title: $page.title") p(page.text)
 }

Slide 62

Slide 62 text

@glaforge A DSL for the model • Templates generate contents • The model describes the website • Our model is described using a Groovy DSL 42

Slide 63

Slide 63 text

@glaforge Sitemap.groovy 43 menu {
 group('Groovy') {
 item ‘Learn', 'learn.html'
 item 'Documentation', 'documentation.html'
 item 'Download', 'download.html'
 item 'Community', 'community.html'
 item 'Ecosystem', 'ecosystem.html'
 }
 
 group('About') {
 item 'Contributing', 'contribute.html'
 item 'Source code', 'https://github.com/groovy/groovy-core'
 item 'Build status', 'buildstatus.html'
 item 'Books', 'learn.html#books'
 item 'Sponsors', 'sponsors.html'
 item 'FAQ', 'faq.html'
 item 'Search', 'search.html'
 } …

Slide 64

Slide 64 text

@glaforge Sitemap.groovy 44 ecosystem {
 project('Grails') {
 description '''Grails is an Open Source, full stack, web application framework for the JVM. It takes advantage of the Groovy programming language and convention over configuration to provide a productive and stream-lined development experience.'''
 url 'http://grails.org/'
 logo 'img/ecosystem/grails.png'
 }
 
 project('Gradle') {
 description '''Gradle is build automation evolved. Gradle can automate the building, testing, publishing, deployment and more of software packages or other types of projects such as generated static websites, generated documentation or indeed anything else.'''
 url 'http://gradle.org'
 logo 'img/ecosystem/gradle.gif'
 }
 …

Slide 65

Slide 65 text

Baking…

Slide 66

Slide 66 text

@glaforge Baking • sitemap.groovy contains the site “data” • MarkupTemplateEngine converts it to pages • Gradle – Compiles the generator – Generates the website – Checks for dead links in generated contents 46

Slide 67

Slide 67 text

@glaforge Deployment • Gradle generates a static website • Can be deployed anywhere • For continuous deployment, we use TeamCity 47

Slide 68

Slide 68 text

@glaforge TeamCity at Groovy • CI Server for Groovy • Tests, builds and releases Groovy • Build plans for JDK 5, 6, 7, 8 and even 9 • Tests every pull request before merge • We test early releases of the JDK (EA and sources) • http://ci.groovy-lang.org?guest=1 48

Slide 69

Slide 69 text

No content

Slide 70

Slide 70 text

@glaforge TeamCity at Groovy • Server is sponsored by • Deployment of Groovy is done through • Releasing Groovy is: – Done through Artifactory plugin – One form + one click 50

Slide 71

Slide 71 text

@glaforge Website deployment A commit on the master branch of website… • Triggers a build • Which generates a static website • Copied to the server if the build is successful 51

Slide 72

Slide 72 text

@glaforge A word on GVM When a release is done: • GVM is notified • Download is made available in GVM • Done through a REST API • API Called directly from TeamCity • Thanks to... a Groovy script! 52

Slide 73

Slide 73 text

@glaforge Groovy build-step in TeamCity • Groovy Build Step plugin – Allows you to write a build step as a Groovy script – Can be used to deploy, copy resources, web hooks ... 53

Slide 74

Slide 74 text

Summary

Slide 75

Slide 75 text

Executable documentation

Slide 76

Slide 76 text

New website

Slide 77

Slide 77 text

Simplified deployment

Slide 78

Slide 78 text

Thanks for your attention!

Slide 79

Slide 79 text

Q & A

Slide 80

Slide 80 text

@glaforge Picture credits London: http://www.100percentoptical.com/images/2014/10/london.jpg Vomit:; http://youoffendmeyouoffendmyfamily.com/wordpress/wp-content/uploads/2011/09/vomit1.jpg Dinos: http://vergapipe.com/wp-content/uploads/2014/11/dinosaurs_wallpapers_free_download.jpg Future: http://www.hdwallsource.com/stunning-future-wallpaper-29256.html/stunning-future-wallpaper-29256 Gears: http://gearsoffate.com/wp-content/uploads/2014/09/Gears2.jpg Surprise: http://www.mentalactif.com/wp-content/uploads/2013/03/SURPRISE.jpg Plane: http://i.imgur.com/esCemkx.jpg Baking: http://www.nlinnovators.nl/wp-content/blogs.dir/1/files_mf/1409922073Navy_baking_bread.jpg 60