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

    View full-size slide

  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.

    View full-size slide

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

    View full-size slide

  4. @codeJENNerator
    About Me

    View full-size slide

  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.

    View full-size slide

  6. @codeJENNerator
    Background

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  9. @codeJENNerator
    img src: https://flic.kr/p/rehEf5

    View full-size slide

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

    View full-size slide

  11. @codeJENNerator
    Types of
    Documentation

    View full-size slide

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

    View full-size slide

  13. @codeJENNerator
    Selecting a Solution

    View full-size slide

  14. @codeJENNerator

    View full-size slide

  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.

    View full-size slide

  16. @codeJENNerator
    Convert to HTML

    View full-size slide

  17. @codeJENNerator
    Convert to PDF

    View full-size slide

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

    View full-size slide

  19. @codeJENNerator
    How to use
    AsciiDoctor

    View full-size slide

  20. @codeJENNerator

    View full-size slide

  21. @codeJENNerator

    View full-size slide

  22. @codeJENNerator
    Asciidoctor Gradle
    Plugin

    View full-size slide

  23. @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
    }

    View full-size slide

  24. @codeJENNerator

    View full-size slide

  25. @codeJENNerator
    Converted to HTML

    View full-size slide

  26. @codeJENNerator
    Demo

    View full-size slide

  27. @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

    View full-size slide

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

    View full-size slide

  29. @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]
    ----

    View full-size slide

  30. IntelliJ Plugin

    View full-size slide

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

    View full-size slide

  32. @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

    View full-size slide

  33. @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

    View full-size slide

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

    View full-size slide

  35. @codeJENNerator
    Overview
    •Sponsored by Pivotal

    •Project Lead - Andy Wilkinson

    •Twitter Account and Official Logo

    View full-size slide

  36. @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

    View full-size slide

  37. @codeJENNerator

    View full-size slide

  38. @codeJENNerator

    View full-size slide

  39. @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

    }

    View full-size slide

  40. @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[]

    View full-size slide

  41. @codeJENNerator

    View full-size slide

  42. @codeJENNerator

    View full-size slide

  43. @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

    View full-size slide

  44. @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"

    }

    ----

    View full-size slide

  45. @codeJENNerator
    Example Response Fields
    |===

    |Path|Type|Description


    |`id`

    |`Number`

    |The greeting's id


    |`message`

    |`String`

    |The greeting's message


    |===

    View full-size slide

  46. @codeJENNerator
    +

    View full-size slide

  47. @codeJENNerator
    +

    View full-size slide

  48. @codeJENNerator

    View full-size slide

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

    View full-size slide

  50. @codeJENNerator
    Strategies

    View full-size slide

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

    View full-size slide

  52. @codeJENNerator

    View full-size slide

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

    View full-size slide

  54. @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 = '[email protected]:jlstrater/groovy-spring-boot-restdocs-example.git'

    pages {

    from(file('build/resources/main/public/html5'))
    }

    }

    View full-size slide

  55. @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 = '[email protected]: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!

    View full-size slide

  56. @codeJENNerator

    View full-size slide

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

    View full-size slide

  58. @codeJENNerator
    Outcomes

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  61. @codeJENNerator
    Conclusion

    View full-size slide

  62. @codeJENNerator

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  65. @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.

    View full-size slide

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

    View full-size slide

  67. @codeJENNerator
    Questions?
    https://flic.kr/p/5DeuzB

    View full-size slide