Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Introduction to Documentation with Asciidoctor

Introduction to Documentation with Asciidoctor

Berlin Groovy User Group talk

jlstrater

June 15, 2017
Tweet

More Decks by jlstrater

Other Decks in Technology

Transcript

  1. Generating Documentation in Groovy Projects with AsciiDoctor Jenn Strater @codeJENNerator

  2. @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 official presentation. • If this view does not support links, the links will work in the pdf. Click the ‘download pdf’ button on the right.
  3. @codeJENNerator https://speakerdeck.com/jlstrater/documentation-berlin-gug https://github.com/jlstrater/doc-example Follow Along

  4. @codeJENNerator About Me

  5. @codeJENNerator About Me - Working at Zenjob. - Just finished

    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.
  6. @codeJENNerator Background

  7. @codeJENNerator Background • Documentation • Static Sites • Google Docs

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

    • Github Wiki • Swagger • Asciidoctor • Who’s responsible? • Devs • Product/Project Manager • QA • Other
  9. @codeJENNerator img src: https://flic.kr/p/rehEf5

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

  11. @codeJENNerator Types of Documentation

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

  13. @codeJENNerator Selecting a Solution

  14. @codeJENNerator

  15. @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.
  16. AsciiDoctor

  17. @codeJENNerator Convert to HTML

  18. @codeJENNerator Convert to PDF

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

    examples
  20. @codeJENNerator How to use AsciiDoctor

  21. @codeJENNerator

  22. @codeJENNerator

  23. @codeJENNerator Asciidoctor Gradle Plugin

  24. @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 }
  25. @codeJENNerator

  26. @codeJENNerator Converted to HTML

  27. @codeJENNerator Demo

  28. None
  29. @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
  30. @codeJENNerator index.adoc == Lists - This is a list item

    - This is another list item
  31. @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] ----
  32. IntelliJ Plugin

  33. @codeJENNerator ➜ test-doc-example ./gradlew asciidoctor BUILD SUCCESSFUL in 4s 1

    actionable task: 1 executed
  34. @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 files of tasks... (ctrl-d to exit) <-------------> 0% WAITING
  35. @codeJENNerator modified: /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 files of tasks... (ctrl-d to exit) <-------------> 0% WAITING > IDLE
  36. @codeJENNerator Overview projects.spring.io/spring-restdocs springrestdocs

  37. @codeJENNerator Overview •Sponsored by Pivotal •Project Lead - Andy Wilkinson

    •Twitter Account and Official Logo
  38. @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
  39. @codeJENNerator

  40. @codeJENNerator

  41. @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
 }
  42. @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[]
  43. @codeJENNerator

  44. @codeJENNerator

  45. @codeJENNerator Generated Snippets • curl-request.adoc • http-request.adoc • httpie-request.adoc •

    http-response.adoc • request body • response body • response-fields.adoc • request-parameters.adoc • request-parts.adoc
  46. @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"
 }
 ----
  47. @codeJENNerator Example Response Fields |===
 |Path|Type|Description
 
 |`id`
 |`Number`
 |The

    greeting's id
 
 |`message`
 |`String`
 |The greeting's message
 
 |===
  48. @codeJENNerator +

  49. @codeJENNerator +

  50. None
  51. @codeJENNerator

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

  53. @codeJENNerator Strategies

  54. @codeJENNerator Strategies • Hook in asciidoctor with the gradle build

    task • Run the asciidoctor test separately (but make sure to run AFTER the tests)
  55. @codeJENNerator

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

  57. @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')) }
 }
  58. @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')) }
 } If you use this method, remember to deploy docs at the same time as the project!
  59. @codeJENNerator

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

  61. @codeJENNerator Outcomes

  62. @codeJENNerator One Year Later • Made it to production! :)

    • Team still happy with Spring REST Docs • Other dev teams like to see the examples
  63. @codeJENNerator Read the docs for more on.. • Asciidoc formatting

    • Other Asciidoctor plugins and extensions • Spring REST Docs specifics
  64. @codeJENNerator Conclusion

  65. @codeJENNerator

  66. @codeJENNerator • Adding Documentation to your Groovy project is easy

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

    with Asciidoctor and Gradle • Asciidoctor can include [live] code snippets in the docs.
  68. @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.
  69. @codeJENNerator Next Steps • Join the Groovy Community on Slack

    groovycommunity.com • Contribute on Github • Join Zenjob!
  70. @codeJENNerator Questions? https://flic.kr/p/5DeuzB