Spring 官方出品的文档生成器, 也太方便了吧

spring-asciidoctor-backends 初体验

本文转载于公众号 蓝色头像

原文链接

本文相关代码已上传 Github

功能亮点

• Spring 官方出品, 使用方便
• 响应式设计, 支持电脑/手机移动端
• 暗黑模式
• Tabs / Code Folding / Code Chomping 等其他拓展功能

前言

对于程序员来说, 写好文档一直是一个比较头疼的问题.

下面主要介绍如何使用 spring-asciidoctor-backends 配合 Asciidoctor 生成 Spring 风格的 html 文档以及 pdf 文档.

Asciidoc 简介

Use AsciiDoc for document markup. Really. It’s actually readable by humans, easier to parse and way more flexible than XML.
— Linus Torvalds

简单来说, Asciidoc 可以理解成加强版的 Markdown.

Asciidoctor 负责解析 Asciidoc 文档, 并最终生成 HTML 5, DocBook 5, manual pages, PDF, and EPUB 3 等格式的文档.

它拥有自动 TOC, 复杂表格(单元格合并), cross references 跨文章 anchor 引用, 脚注, Document Attributes 文档变量等等功能.

在 Java 项目中使用 Asciidoc, 可以更好地使文档文件和代码文件结合, 通过 Asciidoctor Maven/Gradle 插件, 可以更好地和 CI/CD 整合.

Getting Started

以 Gradle 项目为例, 具体参数参考 spring-asciidoctor-backends 文档 和 Asciidoctor Gradle Plugin 文档

添加 Asciidoctor 插件

plugins {
  id 'java'
  id 'java-library'
  id 'org.asciidoctor.jvm.convert' version '3.3.0'
  id 'org.asciidoctor.jvm.pdf' version '3.3.0'
  id 'org.asciidoctor.jvm.epub' version '3.3.0'
}

添加 spring repo

截止到目前, spring-asciidoctor-backends 还在 spring milestone 仓库中

repositories {
  maven { url 'https://maven.aliyun.com/repository/central' }
  mavenCentral()
  maven {
    url "https://repo.spring.io/milestone"
  }
  maven {
    url "https://repo.spring.io/release"
  }
}

配置 asciidoctorExtensions

ext {
  indexFileName = 'index.adoc'
  springAsciidoctorVersion = '0.0.1-M1'
}

configurations {
  asciidoctorExtensions
}

dependencies {
  asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:${springAsciidoctorVersion}"
}

配置 asciidoctor task

asciidoctor {
  baseDirFollowsSourceDir()
  sources {
    include project.ext.indexFileName
  }
  resources {
    from(sourceDir) {
      include 'images/**'
    }
  }
  outputDir file("$buildDir/asciidoc")
  configurations "asciidoctorExtensions"
  outputOptions {
    backends "spring-html"
  }
}

• 其中 sources {} 配置需要转换的文件, 可自行调整

替换 html 文档 logo

目前默认 logo 为 Spring 且无法直接配置修改, 见 issue

我们可以通过 Gradle task, 打包后进行图片的替换

• 添加自己的 svg 图片, src/docs/asciidoc/images/banner-logo.svg
• 配置 Gradle 进行图片替换

asciidoctor.doLast {
  delete file("$buildDir/asciidoc/img/banner-logo.svg")
  copy {
    from file("$buildDir/asciidoc/images/banner-logo.svg")
    into file("$buildDir/asciidoc/img")
  }
}

配置 pdf 输出

• 下载 ttf 字体, 使用了 Sarasa-Gothic 更纱黑体 和 JetBrainsMono 字体

  放到 src/docs/asciidoc/fonts 目录

• 自定义 pdf theme src/docs/asciidoc/themes/sc-theme.yml

• 文档中添加 pdf 相关文档参数, 其中 :pdf-theme: sc 与 sc-theme.yml 名字对应

:pdf-theme: sc
:pdf-fontsdir: fonts
:pdf-themesdir: themes

• 配置 asciidoctorPdf task

asciidoctorPdf {
  baseDirFollowsSourceDir()
  sources {
    include project.ext.indexFileName
  }
  resources {
    from(sourceDir) {
      include 'images/**'
    }
  }
  outputDir file("$buildDir/asciidoc")
}

打包

• 自定义 task, 打包资源

task tarIndexPage(type: Tar) {
  description '打包 html 及 pdf'
    
  dependsOn asciidoctor, asciidoctorPdf
    
  archiveFileName = "index.tar.gz"
  destinationDirectory = file("$buildDir/dist")
  compression = Compression.GZIP
    
  from "$buildDir/asciidoc"
}

• 打包

./gradlew clean tarIndexPage

总结

总的来说, spring-asciidoctor-backends 的使用还是非常简便的, 期待后续版本的完善.