Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

DocuOps & Asciidoctor in a JVM World

382 views

Published on

What is DocuOps. How does Asciidoctor contribute? How to add it to your Maven & Gradle build. Tying all of the tech documentation together in a single project from commit to publish.

Published in: Software
  • Login to see the comments

DocuOps & Asciidoctor in a JVM World

  1. 1. DOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVMDOCUOPS & ASCIIDOCTOR IN A JVM WORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLDWORLD Schalk W. Cronjé  @ysb33r  ysb33r@gmail.com 1
  2. 2. GREETINGSFROM BARCELONA JUG 2
  3. 3. 3
  4. 4. 4
  5. 5. DocuOps: Documentation is an engineering problem. 5 . 1
  6. 6. Go from writing to publication in near-zero effort. 5 . 2
  7. 7. Reduce manual proof reading to absolute minimum that is still sensible. 5 . 3
  8. 8. Reduce the dev-doc distance 5 . 4
  9. 9. Focus on content, not formatting 5 . 5
  10. 10. Write-once, publish multiple formats 5 . 6
  11. 11. Prefer text-based markup 5 . 7
  12. 12. DocuOps is not restricted to technical documents. 5 . 8
  13. 13. DOCSIN JVM WORLD Binary API (javadoc, groovydoc, scaladoc etc.) REST API User documentation 6
  14. 14. ASCIIDOCTOR 7
  15. 15. ASCIIDOCTOR Written in Ruby Runs as AsciidoctorJ via JRuby Runs as Asciidocto.js via Opal transpilation. Standard backends: HTML, Docbook5, PDF, EPUB. 8
  16. 16. ASCIIDOCTORJ 2.1.0RELEASED Fully separate API from implementation engine. Default JRuby engine is Ruby Asciidoctor 2.0 Binary incompatible with AsciidoctorJ 1.6.x Extensions will need to be recompiled. 9 . 1
  17. 17. PLUGGABLE SYNTAX HIGHLIGHTERS Supports CodeRay, Pygments, Highlight.js, Prettify & Rouge Includes dark pygment styles highlightjs-languages attribute 9 . 2
  18. 18. CONVERTER API Easier to register and implement a new backend converter. Bridging APIs for legacy converters. Built-in converters can be extended. 9 . 3
  19. 19. NICETIES Asciidoctorj installed via SDKman. Asciidoctor cheatsheet via asciidoctor(j) --help Delegate unregistered backends 9 . 4
  20. 20. USING ASCIIDOCTOR WITH MAVEN pom.xml Sources go in ${basedir}/src/main/asciidoc. Output goes to ${project.build.directory}/generated-docs. <plugins> <plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.8</version> ... </plugin> </plugins> 10 . 1
  21. 21. USING ASCIIDOC FOR MAVEN SITE Place documents in src/site/asciidoc. Runs independently from src/main/asciidoc. 10 . 2
  22. 22. Gradle is more than a tool for building Java/Groovy/Kotlin etc. It is an advanced pipeline automation tool. 11
  23. 23. Asciidoctor plugin for Gradle is (probably) the most advanced integration between build tooling and documentation production. 12
  24. 24. STATE OF ASCIIDOCTOR GRADLE PLUGINS v1.5.x & v1.6.x in maintenance v2.1.0 released v2.2.0 in progress v3.0.0 in development 13
  25. 25. LEGACY: 1.5.X / 1.6.X Latest releases 1.5.12 & 1.6.1. Now uses external Java process to build. Urgent maintenance xes only. Not guaranteed to work with Gradle 5.0+ Uses AsciidoctorJ 1.5.x/1.6.x as engine 14
  26. 26. 2.0.0 Complete redesign. Some backwards compatibility. Requires Gradle 4.0+. Groovy DSL & Kotlin DSL. 7 subprojects & 10 plugins. (1.5.x: 1 project & 2 plugins). Will probably support Asciidoctor.js in future. 15 . 1
  27. 27. TIMELINE 10 months work First commit 28 May 2018 First alpha release July 2018 Released in-time for Greach 2019 15 . 2
  28. 28. CODING Everything done in Groovy. Mostly statically compiled. Spock 1.2 test framework. TestKit for integration testing. GradleTest for compatibility testing. 15 . 3
  29. 29. 2.X: IMPROVEDGLOBAL CONFIGURATION asciidoctorj { version = '1.6.2' groovyDslVersion = '1.6.0' pdfVersion = '1.5.0-alpha.16' epubVersion = '1.5.0-alpha.8.1' diagramVersion = '1.5.12' options doctype: 'book', ruby: 'erubis' attributes toclevel: 2 } 16 . 1
  30. 30. CUSTOMISE ATTASK LEVEL // Project extension asciidoctorj { attributes toclevel: 2 } asciidoctor { // Task extension asciidoctorj { attributes toc: right } } 16 . 2
  31. 31. FAILING ON WARNINGS asciidoctorj { fatalWarnings ~/missing attribute/ fatalWarnings missingIncludes() } 16 . 3
  32. 32. ASCIIDOCTORJ EXTENSIONS Inline Groovy String. Inline Groovy closure As a Groovy le. As a subproject. As an artifact. 16 . 4
  33. 33. INLINE EXTENSION asciidoctorj { extensions '''block(name: 'BIG', contexts: [':paragraph']) { parent, reader, attributes -> def upperLines = reader.readLines()*.toUpperCase() .inject('') {a, b -> "${a}n${b}"} createBlock(parent, "paragraph", [upperLines], attributes, [:]) }''' } 16 . 5
  34. 34. GROOVY EXTENSION asciidoctorj { extensions { block(name: 'BIG', contexts: [':paragraph']) { parent, reader, attributes -> def upperLines = reader.readLines()*.toUpperCase() .inject('') {a, b -> "${a}n${b}"} createBlock(parent, "paragraph", [upperLines], attributes, [:]) } } 16 . 6
  35. 35. FILE EXTENSION asciidoctorj { extensions file('blockMacro.groovy') } 16 . 7
  36. 36. SUBPROJECTEXTENSION asciidoctorj { extensions project(':blockmacro') } 16 . 8
  37. 37. GROOVY DSL DEPENDENCY asciidoctorj.extensions automatically adds groovy-dsl dependency. To override the version use asciidoctorj.groovyDslVersion. 16 . 9
  38. 38. ARTIFACTEXTENSION configurations { asciidocExt } dependencies { asciidocExt 'group:artifact:1.2.3' } asciidoctor { configurations 'asciidocExt' } 16 . 10
  39. 39. TASK CONFIGURATION Learning from the past all Asciidoctor tasks have an extended set of DSL con guration options. 17 . 1
  40. 40. SOURCES Sources are always speci ed relative to a source root. asciidoctor { sourceDir 'src/docs/asciidoc' sources { include 'index.adoc' } } 17 . 2
  41. 41. OUTPUT Specify where outputs will be written to. asciidoctor { outputDir "${buildDir}/docs" } 17 . 3
  42. 42. SECONDARY SOURCES Non-asciidoc les that are used by backends. Changes to them Gradle up-of-date status. Relative to source root. Some backends add default patterns. asciidoctor { secondarySources { include '**/docinfo*.xml' } } 17 . 4
  43. 43. RESOURCES File that might be processed by backends, and will probably be required in the nal output. Changes to them affect Gradle up-to-date status. asciidoctor { resources { from 'src/images', { include '**/*.png' } } } 17 . 5
  44. 44. CONTROLLING RESOURCE COPY asciidoctor { copyAllResources() copyNoResources() copyResourcesOnlyIf 'html' } 17 . 6
  45. 45. INTERMEDIATE WORKING DIRECTORY Some backends or extensions write working output into source directory. Keep source directory pristine. asciidoctor { useIntermediateWorkDir() } 17 . 7
  46. 46. INTERMEDIATE ARTIFACTS Some extensions create artifacts that might need copying to nal output Implies useIntermediateWorkDir. asciidoctor { withIntermediateArtifacts { include 'diag-*.png' } } 17 . 8
  47. 47. PARALLEL PROCESSING Documents can be converted in parallel. asciidoctor { parallelMode true } 17 . 9
  48. 48. ADDING ADDITIONAL DEPENDENCIES confgurations { asciidocExtensions } dependencies { asciidocExtensions 'group:my-super-extension:1.2.3' } asciidoctor { configurations 'asciidocExtensions' } 17 . 10
  49. 49. FINE-TUNING FORKS Works with processMode of OUT_OF_PROCESS and JAVA_EXEC Similar to JavaForkOptions used elsewhere in Gradle. asciidoctor { forkOptions { minHeapSize = '512m' } } 17 . 11
  50. 50. USING ASCIIDOCTOR DIAGRAM asciidoctor { asciidoctorj { diagramVersion = '1.5.16' } } 17 . 12
  51. 51. ASCIIDOCTOR TASK Generic task, use specialised tasks where applicable. plugins { id 'org.asciidoctor.jvm.convert' version '3.0.0-alpha.3' } asciidoctor { // .... } 18 . 1
  52. 52. SETTING OUTPUTOPTIONS asciidoctor { outputOptions { backends 'html', 'docbook' separateOutputDirs = true } } 18 . 2
  53. 53. PDF PLUGIN plugins { id 'org.asciidoctor.jvm.pdf' version '3.0.0-alpha.3' } asciidoctorPdf { // .... } 19 . 1
  54. 54. FONTS asciidoctorPdf { fontsDir 'src/fonts' } 19 . 2
  55. 55. DOWNLOADA THEME pdfThemes { github 'fancy', { organisation 'asciidoctor' repo 'pdf-themes' tag 'RELEASE_1_0' relativePath 'fancy-theme' } } 19 . 3
  56. 56. LOCAL THEME pdfThemes { local 'myTheme', { styleDir 'src/styles/my-new-style' styleName 'myTheme' } } 19 . 4
  57. 57. USING A THEME asciidoctorPdf { theme 'fancy' } 19 . 5
  58. 58. EPUB PLUGIN plugins { id 'org.asciidoctor.jvm.epub' version '3.0.0-alpha.3' } asciidoctorEpub { // .... } 20 . 1
  59. 59. OUTPUTFORMATS KF8 requires kindlegen. asciidoctorEpub { eBookFormats KF8, EPUB } 20 . 2
  60. 60. USING KINDLEGEN kindlegen { agreeToTermsOfUse = true } 20 . 3
  61. 61. REVEAL.JSPLUGIN plugins { id 'org.asciidoctor.jvm.revealjs' version '3.0.0-alpha.3' } asciidoctorRevealJs { theme 'beige' sourceDir 'src/docs/asciidoc' sources { include 'index.adoc' } revealjsOptions { controls = true verticalCenter = true } } 21
  62. 62. ADDING GEMS plugins { id 'org.asciidoctor.jvm.gems' version '3.0.0-alpha.3' } repositories { maven { url 'http://rubygems-proxy.torquebox.org/releases' } } dependencies { asciidoctorGems 'rubygems:asciidoctor-bibtex:0.3.1' } asciidoctorj { requires 'asciidoctor-bibtex' } 22
  63. 63. WRITING JAVADOC IN ASCIIDOC /** * <h1>Asciidoclet</h1> * * <p>Sample comments that include {@code source code}.</p> * * <pre>{@code * public class Asciidoclet extends Doclet { * private final Asciidoctor asciidoctor = Asciidoctor.Factory * * {@literal @}SuppressWarnings("UnusedDeclaration") * public static boolean start(RootDoc rootDoc) { * new Asciidoclet().render(rootDoc); * return Standard.start(rootDoc); * } * } * }</pre> 23 . 1
  64. 64. WRITING JAVADOC WITH ASCIIDOCLET /** * = Asciidoclet * * Sample comments that include `source code`. * * [source,java] * -- * public class Asciidoclet extends Doclet { * private final Asciidoctor asciidoctor = Asciidoctor.Factory * * @SuppressWarnings("UnusedDeclaration") * public static boolean start(RootDoc rootDoc) { * new Asciidoclet().render(rootDoc); * return Standard.start(rootDoc); * } * } 23 . 2
  65. 65. EXAMPLE API DOCS- STORMPOT Source: http://chrisvest.github.io/stormpot/site/apidocs/stormpot/Poolable.html 23 . 3
  66. 66. USING ASCIIDOCLETWITH BUILDTOOLING Maven: maven-javadoc-plugin plugin. Gradle: asciidoclet artifact. Ant: Via javadoc task. 23 . 4
  67. 67. JDK SUPPORT Up to JDK8. Final changes being made for support JDK11+ 23 . 5
  68. 68. 24 . 1
  69. 69. STAGES 1. Build API docs (groovydoc). 2. Build user documentation (asciidoctor). 3. Build the CHANGELOG (asciidoctor). 4. Build landing page for multiple versions (asciidoctor). 5. Commit build documentation. 6. Publish. 24 . 2
  70. 70. 24 . 3
  71. 71. BUILD& COMMIT gitlab-ci.yml publish: stage: release image: java:8 script: ./gradlew installDocs publishPlugins gitPublishPush -i < dependencies: - jdk8 only: - release 24 . 4
  72. 72. PUBLISHING DOCSFROM CI gitlab-ci.yml pages: stage: release script: ls -la artifacts: paths: - public cache: paths: - .gradle/ only: - pages 24 . 5
  73. 73. ABOUTTHIS… Written in Asciidoc Styled by Reveal.js Orchestrated by Gradle Backend is asciidoctor-revealjs plugin 25
  74. 74. CONTRIBUTING Languages Ruby, Java, Groovy, JavaScript CI Travis, GitLab Pipelines Project How to start Fix docs, bugs. Add features. https://github.com/asciidoctor 26
  75. 75. QUESTIONS? Schalk W. Cronjé @ysb33r ysb33r@gmail.com 27
  76. 76. PROCESSMODESIN GRADLE IN_PROCESS: Gradle worker. OUT_OF_PROCESS: Gradle worker in separate Java process. JAVA_EXEC: Separate Java process using javaexec. Controlled on a per-task basis. Default is JAVA_EXEC 28

×