Introduction to Documentation with Asciidoctor

Slide 1

Slide 1 text

Generating Documentation in Groovy Projects with AsciiDoctor Jenn Strater @codeJENNerator

Slide 2

Slide 2 text

@codeJENNerator Note For Those Viewing Slides Online • Bulleted text like this indicates the key points mentioned on a previous slide. They may not have been included in the ofﬁcial presentation. • If this view does not support links, the links will work in the pdf. Click the ‘download pdf’ button on the right.

Slide 3

Slide 3 text

@codeJENNerator https://speakerdeck.com/jlstrater/documentation-berlin-gug https://github.com/jlstrater/doc-example Follow Along

Slide 4

Slide 4 text

@codeJENNerator About Me

Slide 5

Slide 5 text

@codeJENNerator About Me - Working at Zenjob. - Just ﬁnished a Fulbright Grant to study and research Groovy in Denmark. - I was a senior consultant at Object Partners, Inc. in Minneapolis, MN, USA. - Co-founder of Gr8Ladies and talk about women in the Groovy Community all over the world - Passionate about bring new people into the Groovy community through free introductory workshops called Gr8Workshops.

Slide 6

Slide 6 text

@codeJENNerator Background

Slide 7

Slide 7 text

@codeJENNerator Background • Documentation • Static Sites • Google Docs • Github Wiki • Swagger • Asciidoctor

Slide 8

Slide 8 text

@codeJENNerator Background • Documentation • Static Sites • Google Docs • Github Wiki • Swagger • Asciidoctor • Who’s responsible? • Devs • Product/Project Manager • QA • Other

Slide 9

Slide 9 text

@codeJENNerator img src: https://ﬂic.kr/p/rehEf5

Slide 10

Slide 10 text

@codeJENNerator I hate writing documentation!* img src: https://ﬂic.kr/p/rehEf5

Slide 11

Slide 11 text

@codeJENNerator Types of Documentation

Slide 12

Slide 12 text

Who is your user? img src: http://www.freepik.com/free- vector/user-avatars-pack_762498.html

Slide 13

Slide 13 text

@codeJENNerator Selecting a Solution

Slide 14

Slide 14 text

@codeJENNerator

Slide 15

Slide 15 text

@codeJENNerator Example AsciiDoc = Gr8Data API Guide  Jenn Strater;  :doctype: book  :icons: font  :source-highlighter: highlightjs  :toc: left  :toclevels: 4  :sectlinks:    [introduction]  = Introduction    The Gr8Data API is a RESTful web service for aggregating and displaying gender ratios from various companies across the world. This document outlines how to submit data from your company or team and  how to access the aggregate data.    [[overview-http-verbs]]  == HTTP verbs    The Gr8Data API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Slide 16

Slide 16 text

AsciiDoctor

Slide 17

Slide 17 text

@codeJENNerator Convert to HTML

Slide 18

Slide 18 text

@codeJENNerator Convert to PDF

Slide 19

Slide 19 text

@codeJENNerator Other Formats • ePub • DeckJS • RevealJS https://github.com/asciidoctor/asciidoctor-gradle- examples

Slide 20

Slide 20 text

@codeJENNerator How to use AsciiDoctor

Slide 21

Slide 21 text

@codeJENNerator

Slide 22

Slide 22 text

@codeJENNerator

Slide 23

Slide 23 text

@codeJENNerator Asciidoctor Gradle Plugin

Slide 24

Slide 24 text

@codeJENNerator Install buildscript { repositories { jcenter() } dependencies { classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.11' } } plugins { id 'org.asciidoctor.convert' version '1.5.3' }   asciidoctor { sourceDir = file('src/docs') sources { include 'index.adoc' } backends = ['html','pdf'] outputDir file('build/docs') attributes \ 'source-highlighter': 'coderay', 'toc': '', 'idprefix': '', 'idseparator': '-', 'allow-uri-read': true }

Slide 25

Slide 25 text

@codeJENNerator

Slide 26

Slide 26 text

@codeJENNerator Converted to HTML

Slide 27

Slide 27 text

@codeJENNerator Demo

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

@codeJENNerator src/docs/index.adoc = Introduction to Documentation  Jenn Strater;  :doctype: book  :icons: font  :source-highlighter: highlightjs  :toc: left  :toclevels: 4  :sectlinks:    [introduction]  = Introduction    This is an example asciidoc for the purposes of this demo. [[subsection]] == Subsection In addition to main sections, you can have subsections

Slide 30

Slide 30 text

@codeJENNerator index.adoc == Lists - This is a list item - This is another list item

Slide 31

Slide 31 text

@codeJENNerator index.adoc == Source Code You can also include source code examples like this `Hello World` script: [source,groovy] ---- println 'Hello, World!' ---- You can also reference source code within a project like this: [source,groovy, linenums] ---- include::{sourcedir}/App.groovy[lines=5..7] ----

Slide 32

Slide 32 text

IntelliJ Plugin

Slide 33

Slide 33 text

@codeJENNerator ➜ test-doc-example ./gradlew asciidoctor BUILD SUCCESSFUL in 4s 1 actionable task: 1 executed

Slide 34

Slide 34 text

@codeJENNerator ➜ doc-example git:(master) ✗ ./gradlew asciidoctor -t Continuous build is an incubating feature. BUILD SUCCESSFUL in 0s 1 actionable task: 1 up-to-date Waiting for changes to input ﬁles of tasks... (ctrl-d to exit) <-------------> 0% WAITING

Slide 35

Slide 35 text

@codeJENNerator modiﬁed: /Users/jstrater/Documents/dev/doc-example/src/docs/index.adoc Change detected, executing build... BUILD SUCCESSFUL in 3s 1 actionable task: 1 executed Waiting for changes to input ﬁles of tasks... (ctrl-d to exit) <-------------> 0% WAITING > IDLE

Slide 36

Slide 36 text

@codeJENNerator Overview projects.spring.io/spring-restdocs springrestdocs

Slide 37

Slide 37 text

@codeJENNerator Overview •Sponsored by Pivotal •Project Lead - Andy Wilkinson •Twitter Account and Oﬃcial Logo

Slide 38

Slide 38 text

@codeJENNerator Spring REST Docs Talks • Documenting RESTful Apis - SpringOne2GX 2015 Andy Wilkinson • Writing comprehensive and guaranteed up-to-date REST API documentation - SpringOne Platform 2016 Anders Evers • Greach 2017 - A Test-Driven Approaches to Documenting RESTful APIs with Groovy - Greach 2017 Jenn Strater

Slide 39

Slide 39 text

@codeJENNerator

Slide 40

Slide 40 text

@codeJENNerator

Slide 41

Slide 41 text

@codeJENNerator Gradle asciidoctor {  dependsOn test  sourceDir = file('src/docs')  outputDir "$projectDir/src/main/resources/public"  + inputs.dir snippetsDir  backends 'html5'  attributes 'source-highlighter' : 'prettify',  'imagesdir':'images',  'toc':'left',  'icons': 'font',  'setanchors':'true',  'idprefix':'',  'idseparator':'-',  'docinfo1':'true',  + 'snippets': snippetsDir  }

Slide 42

Slide 42 text

@codeJENNerator Add Snippets to AsciiDoc == Errors    Whenever an error response (status code >= 400) is returned, the body will contain a JSON object  that describes the problem. The error object has the following structure:    include::{snippets}/error-example/response-fields.adoc[]    For example, a request that attempts to apply a non-existent tag to a note will produce a  `400 Bad Request` response:    include::{snippets}/error-example/http-response.adoc[]    [[resources]]  = Resources    include::resources/example.adoc[]

Slide 43

Slide 43 text

@codeJENNerator

Slide 44

Slide 44 text

@codeJENNerator

Slide 45

Slide 45 text

@codeJENNerator Generated Snippets • curl-request.adoc • http-request.adoc • httpie-request.adoc • http-response.adoc • request body • response body • response-ﬁelds.adoc • request-parameters.adoc • request-parts.adoc

Slide 46

Slide 46 text

@codeJENNerator Example Http Response [source,http,options="nowrap"]  ----  HTTP/1.1 200 OK  Content-Type: application/json;charset=UTF-8  Content-Length: 37    {  "id" : 1,  "message" : "Hello"  }  ----

Slide 47

Slide 47 text

Slide 48

Slide 48 text

@codeJENNerator +

Slide 49

Slide 49 text

@codeJENNerator +

Slide 50

Slide 50 text

No content

Slide 51

Slide 51 text

@codeJENNerator

Slide 52

Slide 52 text

@codeJENNerator Build Docs src/docs index.adoc src/main/ resources/public/ html5 index.html

Slide 53

Slide 53 text

@codeJENNerator Strategies

Slide 54

Slide 54 text

@codeJENNerator Strategies • Hook in asciidoctor with the gradle build task • Run the asciidoctor test separately (but make sure to run AFTER the tests)

Slide 55

Slide 55 text

@codeJENNerator

Slide 56

Slide 56 text

@codeJENNerator http://api.example.com/docs

Slide 57

Slide 57 text

@codeJENNerator Publish Docs to Github Pages publish.gradle buildscript {  repositories {  jcenter()  }    dependencies {  classpath 'org.ajoberstar:gradle-git:1.1.0'  }  }    apply plugin: 'org.ajoberstar.github-pages'    githubPages {  repoUri = 'git@github.com:jlstrater/groovy-spring-boot-restdocs-example.git'  pages {  from(file('build/resources/main/public/html5')) }  }

Slide 58

Slide 58 text

Slide 59

Slide 59 text

@codeJENNerator

Slide 60

Slide 60 text

@codeJENNerator http://jlstrater.github.io/groovy-spring-boot-restdocs-example

Slide 61

Slide 61 text

@codeJENNerator Outcomes

Slide 62

Slide 62 text

@codeJENNerator One Year Later • Made it to production! :) • Team still happy with Spring REST Docs • Other dev teams like to see the examples

Slide 63

Slide 63 text

@codeJENNerator Read the docs for more on.. • Asciidoc formatting • Other Asciidoctor plugins and extensions • Spring REST Docs speciﬁcs

Slide 64

Slide 64 text

@codeJENNerator Conclusion

Slide 65

Slide 65 text

@codeJENNerator

Slide 66

Slide 66 text

@codeJENNerator • Adding Documentation to your Groovy project is easy with Asciidoctor and Gradle

Slide 67

Slide 67 text

@codeJENNerator • Adding Documentation to your Groovy project is easy with Asciidoctor and Gradle • Asciidoctor can include [live] code snippets in the docs.

Slide 68

Slide 68 text

@codeJENNerator • Adding Documentation to your Groovy project is easy with Asciidoctor and Gradle • Asciidoctor can include [live] code snippets in the docs. • I still hate writing boilerplate documentation, but at least it’s a little less painful now.

Slide 69

Slide 69 text

@codeJENNerator Next Steps • Join the Groovy Community on Slack groovycommunity.com • Contribute on Github • Join Zenjob!

Slide 70

Slide 70 text

@codeJENNerator Questions? https://ﬂic.kr/p/5DeuzB