Introduction to Documentation with Asciidoctor

Generating Documentation in Groovy Projects with AsciiDoctor Jenn Strater @codeJENNerator

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

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

@codeJENNerator About Me

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

@codeJENNerator Background

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

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

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

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

@codeJENNerator Types of Documentation

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

@codeJENNerator Selecting a Solution

@codeJENNerator

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

AsciiDoctor

@codeJENNerator Convert to HTML

@codeJENNerator Convert to PDF

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

@codeJENNerator How to use AsciiDoctor

@codeJENNerator

@codeJENNerator Asciidoctor Gradle Plugin

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

@codeJENNerator

@codeJENNerator Converted to HTML

@codeJENNerator Demo

@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

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

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

IntelliJ Plugin

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

@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

@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

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

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

@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

@codeJENNerator

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

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

@codeJENNerator

@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

@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"  }  ----

@codeJENNerator +

@codeJENNerator

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

@codeJENNerator Strategies

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

@codeJENNerator

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

@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')) }  }

@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!

@codeJENNerator

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

@codeJENNerator Outcomes

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

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

@codeJENNerator Conclusion

@codeJENNerator

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

with Asciidoctor and Gradle • Asciidoctor can include [live] code snippets in the docs.

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.

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

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

Introduction to Documentation with Asciidoctor

Introduction to Documentation with Asciidoctor

More Decks by jlstrater

Other Decks in Technology

Featured

Transcript